For API functions that support user authentication, Talent Suite supports (from release 10.0) a token-based authorization mechanism based on OAuth 2.0. This enables users to obtain an access token using a browser-based flow, and to use this token to authorize API calls.

Why use token-based authorization?

• Token-based authorization decouples API authorization from the primary sign-on mechanism. In particular, token-based authorization is compatible with single sign-on mechanisms such as SAML.
• Token-based authorization enhances security since users aren’t required to share their passwords with third-party applications, nor do such applications need to be granted access to privileged credentials.
• Token-based authorization enables users to revoke authorization granted to specific apps or sites, without changing their primary login credentials (e.g. password).

How does token-based authorization work?

The app generates an unguessable state value and stores this, for example in a cookie in the case of a browser-based app. This value is used to defend agains cross-site request forgery attacks, as per section 10.12 of the OAuth 2.0 specification.

The app then redirects the user to servlet/ekp/authorize, including response_type, client_id, redirect_uri and state query string parameters. The value of response_type should be code. Talent Suite does not require client registration, therefore the value of client_id should be set to anonymous.

As of release 10.0, Talent Suite does not define any scopes. Therefore the scope parameter defined in OAuth 2.0 may be omitted.

For example, assuming a redirect_uri value of https://client.example.com/cb, the app redirects to https://ekp.example.com/ekp/servlet/ekp/authorize?response_type=code&client_id=anonymous&redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom&state=xyz.

After signing in the user and obtaining authorization, Talent Suite redirects the user back to redirect_uri, passing an authorization code and the state value, for example https://client.example.com/cb?code=EKP000010561-35f8fa2b8864bf3d4efdbf07c88a17ff85a51143-ef0447f1c736150c17788c705cae1c84186cef0e&state=xyz. The app checks that the state value matches the value passed, rejecting the response otherwise.

The app then exchanges the authorization code for an access token by sending an HTTP POST request to servlet/ekp/token with parameters grant_type, code and redirect_uri. The value of grant_type should be authorization_code. The values of code and redirect_uri should be the returned authorization code and original redirect_uri respectively. Note that this request does not require client authentication; in particular, client_id and client_password are not required. Assuming that code and redirect_uri are valid, the app receives a JSON response similar to the following.

{
  "access_token": "EKP000010562-d0122ba7466f0e41942fed6273a5fc30991dc2ef",
  "token_type": "Bearer"
}

The app can then authorize API calls by including an Authorization HTTP request header with the scheme of Bearer, for example:

Authorization: Bearer EKP000010562-d0122ba7466f0e41942fed6273a5fc30991dc2ef

Access tokens do not themselves expire. However an access token cannot be used if the account of the user who authorized it expires or is marked as inactive.