CORE API Tokens

• JSON Web Tokens (JWT): Tokens that conform to the JSON Web Token standard and contain information in the form of claims. These are self-contained which means it is not necessary for the issuer to call the server to validate the token.
• Opaque Tokens: Tokens in a proprietary format that typically contain some identifier information in a server’s persistent storage. To validate an opaque token, the recipient needs to call the server that issued the token.

CORE API primarily uses the following token-based authentication.

ID Token

An ID Token is a JWT (JSON web token), that is, a cryptographically signed Base64-encoded JSON object. The ID Token contains user profile attributes represented in the form of claims. These claims are statements about the user, which can be trusted if the consumer of the token can verify its signature. The ID Token is consumed by the application to get user information like the user's name, email, and so forth, typically used for UI display. You can get an ID Token for a user after they successfully authenticate. You must verify the ID Token's signature before storing and using it. You will need to decode this token to read the claims (or attributes) of the user. The JWT website provides a list of libraries you can use to decrypt the ID Token. It was added to the OIDC specification as an optimization so the application can know the identity of the user, without having to make an additional network request. The ID Token conforms to an industry standard and consists of three parts:

1. Header: Contains the type of token and hash algorithm used on the contents of the token.

The header consists of two parts:

• kid—the id of the key used to sign the payload
• alg—the hashing algorithm used, such as HMAC SHA256 or RSA

Example:

Response

2. Body:

   Also called the payload, it contains the identity claims about a user. There are some claims with registered names for things like the issuer of the token, subject of the token (who the claims are about), and time of issuance. If ID Token is returned in URLs, care must be taken to keep the JWT within the browser size limitations for URLs.

The second part of the token is the payload, which contains the claims. Claims are metadata about the user. CORE ID tokens include the following claims:

Claim	Description
aud	Audience. Either a single case-sensitive string or URI or an array of such values that uniquely identify the intended recipients of this JWT. For a CORE issued ID token, this will be the Client ID of your CORE application. This is a registered claim according to the JWT Specification
auth_time	The time the ID token was authorized.
exp	Expiration time. A number representing a specific date and time in the format “seconds since epoch” as defined by POSIX6. This claim sets the exact moment from which this JWT is considered invalid. This is a registered claim according to the JWT Specification
iat	Issued at time. A number representing a specific date and time (in the same format as exp) at which this JWT was issued. This is a registered claim according to the JWT Specification
iss	Issuer. A case-sensitive string or URI that uniquely identifies the party that issued the JWT. For a CORE issued ID token, this will be the URL of your CORE tenant
sub	An identifier for the user, unique among all CORE accounts and never reused. A CORE account can have multiple emails at different points in time, but the sub value is never changed. Use sub within your application as the unique-identifier key for the user e.g., github|1234567890

Example:

Response

3. Signature:

The signature is used to verify that the sender of the JWT is who it says it is and to ensure that the message did not change along the way. To create the signature, sign a concatenation of the encoded header, the encoded payload, and a secret with the specified algorithm. For example, if you use the HMAC SHA256 algorithm, the signature is created in the following way:

HMACSHA256(base64UrlEncode(header) + "." + base64UrlEncode(payload), secret)

How to Get an ID Token?

The ID Token can be returned while authenticating the CORE API user. This includes a call to the authentication API. To retrieve an ID token, the response type should consist of ID token, both for client-side and server-side authentication flows. To know more click here.

Validate an ID Token

Typically, it is critical that you validate an ID token before you use it, but as you are communicating directly with CORE over an intermediary-free HTTPS channel and using your client secret to authenticate yourself to CORE, rest assured that the token you receive comes from CORE and is valid. However, as a best practice, we recommend validating the ID.
Since most API libraries combine the validation with the work of decoding Base64 and parsing JSON, you probably end up validating the token anyway as you access the fields in the ID token. To validate an ID Token, an application needs to verify the signature as well as validate the standard claims of the token. Each of these steps is discussed in more detail below.
Most JWT libraries will take care of the token validation for you automatically, so be sure to reference the Libraries for Token Signing/Verification section of JWT.io to find a JWT library for your platform and programming language.
To validate the ID Token, verify the following:

Verify the Signature

The signature is used to verify the sender of the token and to ensure that the message does not change along the way. Remember that the ID Token is always a JWT and the signature is created using its header and payload, secret and hashing algorithm being used (as specified in the header: HMAC, SHA256or RSA). The way to verify it depends on the hashing algorithm.

• For HS256, the APIs Signing Secret is used. You can find this information in your APIs Settings.

  Note that the field is only displayed for APIs that use HS256.

• For RS256, the tenant's JSON Web Key Set (JWKS) is used. Your tenant's JWKS is
  

   /.well-known/openid-configuration/jwks 

  The most secure practice, and our recommendation, is to use RS256.

  Verify the Claims

  After the application verifies the token's signature, the next step is to validate the standard claims of the token's payload. The following validations need to be made:

• Token expiration: The current date/time must be before the expiration date/time listed in the exp claim (which is a UNIX timestamp).
• Token issuer: The issuer claim denotes the issuer of the JWT. The value must match the URL of your CORE API tenant. For JWTs issued by CORE API, iss holds your CORE API domain with a https://prefix and a / suffix: https://bqecore.com/.
• Token audience: The aud claim identifies the recipients that the JWT is intended for. The value must match the Client ID of your CORE API application.
  
  

  How to Control the Contents of an ID Token?

  The attributes included in the issued ID Token are controlled by the use of a parameter called scope.

• If the scope is set to openid, then the ID Token will contain only the iss, sub, aud, exp and iat claims.
• If the scope is set to openid email, then the ID Token will contain additionally the email and email_verified claims.
• If the scope is set to openid profile, then the ID Token will contain all default profile claims, which are: name, family_name, given_name, middle_name, nickname, preferred_username, profile, picture, website, gender, birthdate, zoneinfo, locale, and updated_at.

 GET /connect/userinfo

Access Token

POST /connect/token

POST /connect/revocation

/callback?code=BPPLN3Z4qCTvSNOy

{
  "error": "invalid_grant"
}