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>'
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.
To dynamically retrieve public keys from a JWKS endpoint, specify the location of the JWKS.
To store a static algorithm secret or public key, the name of the JWT signing algorithm.
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:|
|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.|
JWTs are made up of the following sections:
- Verify Signature
Each section contains information that is output into Base64Url encoded strings.
For the header signing algorithm, Tamr Core supports encryption and signing in accordance with OpenID specifications, excluding “none”.
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.
|“aud”||Required. The resource server that is the audience receiving the JWT. Must be set to |
|“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.|
|“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.|