SDK Authentication

This section shows how to configure an MPC node to accept various kinds of SDK authentication. See this section for more about how to handle authentication from an SDK user perspective.

Authentication with API Keys

The configuration file can contain a number of API keys. In the following there are three API keys.

[Authentication]
  
TokenLifetime = "5m"
  
[[Authentication.APIKeys]]
  APIKey = "1PebMT+BBvWvEIrZb/UWIi2/1aCrUvQwjksa0ddA3mA="
  ApplicationID = "app1"
  
[[Authentication.APIKeys]]
    APIKey = "FfrI+hyZAiVosAi53wewS0U1SsXKR0AEHZBM088rOeM="
    ApplicationID = "app1"

[[Authentication.APIKeys]]
    APIKey = "NaseBBHEzG7KqmdqTH/vJZeYeZ7UCtCfsHra6QK9DHo="
    ApplicationID = "app2"

Each APIKey contains the base64 encoded SHA-256 hash of the actual API key. The hash of the API key apikey1 can for example be generated with the following command:

echo -n "apikey1" | openssl dgst -sha256 -binary | openssl base64

When logging in with an API key, the SDK will log in to a specific application in the MPC node. If the application does not exist, it will be created automatically. In the above example, the two first API keys are hashes of apikey1 and apikey2 and they are configured to map to the application app1. The third API key, apikey3 maps to the application app2.

Crypt hashes with the following algorithms are also supported: MD5, SHA256, SHA512, bcrypt, Argon2i, Argon2id. Some examples:

CodeAlgorithmExample
1MD5APIKey = "$1$deadbeef$Q7g0UO4hRC0mgQUQ/qkjZ0"
5SHA256APIKey = "$5$saltstring$5B8vYYiY.CVt1RlTTf8KbXBH3hsxY/GNooZaBBGWEc5"
6SHA512APIKey = "$6$saltstring$svn8UoSVapNtMuq1ukKS4tPQd8iKwSMHWjl/O817G3uBnIFNjnQJuesI68u4OTLiBFdcbYEdFCoEOfaS35inz1"
2abcryptAPIKey = "$2a$05$/OK.fbVrR/bpIqNJ5ianF.Sa7shbm4.OzKpvFnX1pQLmQW96oUlCq"
argon2iArgon2iAPIKey = "$argon2i$v=19$m=65536,t=2$c29tZXNhbHQ$IMit9qkFULCMA/ViizL57cnTLOa5DiVM9eMwpAvPwr4"
argon2idArgon2idAPIKey = "$argon2id$v=19$m=65536,t=2,p=4$c29tZXNhbHQ$GpZ3sK/oH9p7VIiV56G/64Zo/8GaUw434IimaPqxwCo"

Authentication with Client Certificates (mTLS)

The MPC node can also be configured to require SDKs to authenticate using 2-way TLS (mTLS).

# Setting related to authentication of users based on TLS client certificates.
[TLSUserAuthentication]
  # Points to a file containing PEM encoded certificates of CAs from which client certificates are accepted.
  #ClientCAFile = ""
  # Contains a comma separated list of base64 encoded certificates of CAs from which client certificates are accepted.
  #ClientCAList = ""
  # Enable OCSP validation of client certificates.
  #OCSP = false
  # Require the client to send a stapled OCSP response, otherwise validation will fail.
  #OCSPRequireStapling = false
  # If true then only the leaf certificate is validated. Otherwise, the entire chain is validated.
  #OCSPValidateLeafOnly = false
  # Lifetime of cached OCSP responses, e.g "1h30m". A value of 0 means that ValidUntil from the OCSP response
  # is used, otherwise the value of CacheTTL is used if it comes before ValidUntil.
  #OCSPCacheTTL = "10m"
  # Use this URL for all OCSP responders, regardless of what the certificate says.
  #OCSPResponderURL = ""
  # Use this hash algorithm for OCSP requests, usually SHA-1 or SHA-256. If empty then SHA-256 is used.
  #OSCPHashAlgorithm = ""

  # If no applications are specified, all certificates will be granted access, and given an ID deduced from the
  # Subject and Issuer of the certificate
  # Access to applications is given based on values set in the certificates matching the values set in the filters below.
  # To get a list of OIDs, here is an example:
  # openssl list -objects | grep -i ", 2.5.4"
  # The following text strings can also be used as keys:
  # "commonName", "country", "locality", "stateOrProvince", "streetAddress", "organization", "organizationalUnit",
  # "postalCode", "serialNumber", "givenName", and "surname"
  # For values expecting an array of strings, use "v1, v2"
  #[[TLSUserAuthentication.Applications]]
  #ID = "MyApplicationID"
  #[[TLSUserAuthentication.Applications.Filters]]
  #"2.5.4.3" = "value 00"             # commonName
  #"2.5.4.6" = "value 01, value 02"   # country
  #"2.5.4.11" = "value 03"            # organizationalUnit
  #[[TLSUserAuthentication.Applications.Filters]]
  #"2.5.4.3" = "value 10"   # commonName
  #"serialnumber" = "value 13"

See this section for more about how to use the SDK with client certificdate authentication.

Authentication with OIDC

When instantiating an SDK for an MPC node in the TSM, you have the option to authenticate using an OIDC access token. To do this, add a section similar to this to the node configuration file:

[OIDCAccessTokenAuthentication]

  # List of supported OIDC issuer URLs.
  #OIDCIssuers = []
  
  # Configuration for applications that are allowed to access the TSM
  #[[OIDCAccessTokenAuthentication.AccessTokens]]
  
    # The ID of the application to authenticate, or a reference to a claim which value should
    # be used as application ID. Application IDs must match the regex ^[a-zA-Z0-9_-]+$. This
    # will map to a certain set of key IDs.
    # ApplicationID = "application ID" | "$CLAIM:claim"

    # Must match audience (aud) in access token
    # Audience = "audience value"

    # EITHER
    #   The URL of the discovery document for this access token, used to retrieve the public
    #   key. Defaults to issuer + "/.well-known/openid-configuration".
    # OR
    #   if PublicKey is specified, DiscoveryDocURL is ignored.
    # DiscoveryDocURL = issuer + "/.well-known/openid-configuration"

    # This is a base64 encoding of the players public key. A public key can be generated
    # from the private key using the following OpenSSL commands:
    #
    #     openssl ec -inform DER -in private.key -pubout -outform DER -out public.key
    #     openssl base64 -A -in public.key; echo
    #
    # PublicKey = "BA3E64=="

    # The claims which the access token needs to match. If no claims are required, you still
    # need to add an empty section.
    #[[OIDCAccessTokenAuthentication.AccessTokens.claims]]
    #  claim0 = "claim value 0"
    #[[OIDCAccessTokenAuthentication.AccessTokens.claims]]
    #  claim1 = "claim value 1"
    #  claim2 = "claim value 2"

The MPC node(s) will then validate the access token by

  • Verifying the signature by getting the public key from the DiscoveryDocURL.
  • If the exp-claim has been set, the expiration time will be compared to the current time on the MPC node, and authentication will be rejected if the token has expired. If the nodes and the identity provider are in different timezones, you need to make sure the expiration time is offset accordingly.
  • Comparing the claims in the access token to what has been specified in the configuration file for the TSM node
  • If valid, the MPC node will map the user identity to the application ID specified in the config file, or, alternatively, to the application ID specified in a specific claim.

📘

Caveat

Do not use the same OIDC access token for authenticating towards different TSM nodes. If you use this approach, you risk one node impersonating a user, by sending a received access token to the other nodes.