Authentication with Base64 UUID Tokens

To authenticate your API calls, you need to supply basic credentials. Your credentials are the base64 encoding of your username and password.

You can generate encoded credentials in a number of ways, including this shell echo command:

echo -n '<username>:<password>' | openssl base64

This command returns your encoded credentials, which you can supply in all future API calls.

To authenticate your API requests to the server, you include the encoded credentials in an Authorization: BasicCreds header. Replace <your-credentials> in the example below with your encoded credentials, as generated above.

curl -X <method> --header 'Authorization: BasicCreds <your-credentials>'

Authentication with JSON Web Tokens (JWT)

As an alternative to a base64-encoded username and password, the Tamr Core API supports the use of JSON web tokens for authentication and authorization of externally-managed users (that is, LDAP or SAML is integrated with your Tamr Core instance). When you use JWTs, you send a bearer token with each API call. For example:

curl -X <method> --header 'Authorization: Bearer <your-jwt>'

You generate the JWT and pass it to Tamr Core with every API call for validation. For more information about JWTs, see JWT.IO.

For JWT validation, Tamr supports both statically-configured algorithm secrets or public keys and dynamically retrieving public keys from a JWKS endpoint. See Configuring JWT Use.

The workflow for using JWT with the Tamr Core API follows.

Define settings for Tamr Core configuration variables.
Verify that Tamr Core is configured to use an external service for authenticating and authorizing users (such as LDAP or SSO).
Verify that each user who is seeking JWT authentication has successfully logged into the system at least once.
Configure the system that generates your JWTs. This includes:

Supplying ‘tamr-auth’ for the “aud” claim.
Supplying values for the other required claims: “iss”, “sub”, “exp”, and “iat”.
Determining whether to use the “groups” public claim for user authorization, and if so verifying that the groups you supply are identical to the user groups configured in Tamr Core.
If using a JWKS, supplying a value for the “kId” claim .

Send the generated token with all required claims as a bearer token with your calls to Tamr Core API endpoints.

Tamr Core validates the JWT based on the values in the claims and provides or denies access based on that information.

Configuring JWT Use

Configuration Variable	Description
TAMR_AUTH_JWKS_URI	To dynamically retrieve public keys from a JWKS endpoint, specify the location of the JWKS.
TAMR_AUTH_JWT_ALGORITHM	To store a static algorithm secret or public key, the name of the JWT signing algorithm. If you specify a public key algorithm (RS or EC), then TAMR_AUTH_JWT_PUBLIC_KEY must specify a key of the corresponding type. If you specify an HMAC algorithm, TAMR_AUTH_JWT_SECRET must specify the secret. For allowed algorithm values, see Configuration Variable Reference.
TAMR_AUTH_JWT_PUBLIC_KEY	To store a static public key, the base64 encoded public key to use with the RSA or ECDSA algorithm. Public keys should be specified in PKCS#8 format, for example:`-----BEGIN PUBLIC KEY----- MIGfMA... . . . -----END PUBLIC KEY-----`
TAMR_AUTH_JWT_SECRET	To store a static algorithm secret, the secret to use with the HMAC algorithm.
TAMR_AUTH_JWT_ISSUER	Required. The expected value of the JWT issuer claim.
TAMR_AUTH_JWT_USERNAME_CLAIM_NAME	The name of the JWT claim that contains the Tamr Core username of the user being authenticated. Defaults to “sub”.
TAMR_AUTH_JWT_LEEWAY_SECONDS	The amount of additional time (in seconds) to allow for validating JWT expiration time and issued at claims.

See the Configuration Variable Reference and Setting Configuration Variables.

JWT Header and Payload

JWTs are made up of the following sections:

Header
Payload
Verify Signature

Each section contains information that is output into Base64Url encoded strings.

Header

For the header signing algorithm, Tamr Core supports encryption and signing in accordance with OpenID specifications, excluding “none”.

Payload

Tamr Core uses information sent in the following registered claims and public claims. You include these claims in the bearer token you send to Tamr Core.

Note: In addition to the claims listed here, Tamr Core also uses information sent in the claim specified by the TAMR_AUTH_JWT_USERNAME_CLAIM_NAME configuration variable. Other claims are ignored.

Registered Claim	Description
“aud”	Required. The resource server that is the audience receiving the JWT. Must be set to `tamr-auth`.
“iss”	Required. The principal that is issuing the JWT. Authenticated against the value for the TAMR_AUTH_JWT_ISSUER configuration variable.
“sub”	Required. The unique identifier of the end user. Typically, this is the claim specified by the TAMR_AUTH_JWT_USERNAME_CLAIM_NAME configuration variable. Authenticated against a Tamr Core username that has previously logged in to the system successfully. Note: If the TAMR_AUTH_JWT_USERNAME_CLAIM_NAME configuration variable specifies a different claim (registered, public, or private) as the source of the Tamr Core username, Tamr Core authenticates the username based on the value provided by that claim instead.
“exp”	Required. The expiration time after which the JWT must not be accepted for processing.
“iat”	Required. The time when the JWT was issued.
“jti”	Optional. The unique identifier for the JWT to prevent collisions among values produced by different issuers. Recommended.

Public Claim	Description
“client_id”	Optional. The client identifier of the client that requested the bearer token.
“name”	Optional. The user’s name.
“email”	Optional. The user’s email address.
“groups”	Optional. If you use Tamr Core groups to authorize user access to policy resources, and you have mapped the Tamr Core groups to external groups, you can use this field to identify one or more user groups that the user belongs to. The full external group name must match the Tamr Core group name exactly, including case. See Roles for Users and Groups and Mapping Tamr Core Groups to LDAP Groups.By default, Tamr Core uses only roles granted directly to the user in Tamr Core to authorize access.