APIs

API Endpoints

API calls are protected by JWT access tokens, which are initially created and sent to the client application upon successful authentication. Resource servers will validate the access token and check for both audience and scope before allowing a client request to continue.

For more information about validating access tokents, see here.

Note that Node.js applications can use the “authenticate” decorator to simplify this process. See services-auth for details.

Below is an example of a JWT Access Token.

Encoded JWT Access Tokens

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwianRpIjoidW5pcXVland0aWQiLCJndHkiOiJhdXRob3JpemF0aW9uX2NvZGUiLCJhenAiOjkwMTksImF1ZCI6WyJodHRwczovL215LmRvbWFpbi5vcmcvX2FwaS9hdXRoL215dGVuYW50Il0sInNjb3BlIjoiYXV0aC5jbGllbnRzLmxpc3QiLCJpYXQiOjE2MjIxMzg5NDgsImV4cCI6MTYyMjE0MjU0OCwiaXNzIjoiaHR0cHM6Ly9teS5kb21haW4ub3JnL19hcGkvYXV0aC9teXRlbmFudCJ9.y209KU6qNkmOiYijnTHlYIZHHxiSbpQt3uB_K5TiXh0

For more information on JWT tokens, visit https://jwt.io.

Audience/Resource Servers

These access tokens contain a set of claims in the form of name-value pairs. One of these claims is the audience (“aud” for short), which contains the list of resource server URLs that the token grants access to.

The encoded JWT access token, above, has been decoded, below (through https://jwt.io).

Decoded JWT Access Token

The decoded JWT token is a JSON object with specific name-value pairs, known as claims. The relevant claim here is "aud": ["https://my.domain.org/_api/auth/mytenant"]. This tells the resource server that any client application bearing this token will be granted access to that specific server.

{
  "sub": "1234567890",
  "jti": "uniquejwtid",
  "gty": "authorization_code",
  "azp": 9019,
  "aud": [
    "https://my.domain.org/_api/auth/mytenant"
  ],
  "scope": "auth.clients.list",
  "iat": 1622138948,
  "exp": 1622142548,
  "iss": "https://my.domain.org/_api/auth/mytenant"
}

Scopes

These access tokens also contain the scope (aka permissions) claim, which tells the resource server which services the token grants access to.

For more information about scopes and permissions, visit Permissions.

To see how to create new permissions, visit Permissions How-Tos;

API Audience and Scope Configuration

In order for the token-protected API endpoint to be accessible to the client application, the following configurations must take place:

1. The client must be authorized to access the resource server. If using implicit flow, the “token” response type must be included in the application settings.
2. A role must include the required scopes/permissions for the services requested.
3. The role containing the scope(s) and the corresponding user must be added to a User Group.
4. The User Group must be linked with the client application.
5. The client-side authentication request must include the “audience” claim, which includes the corresponding resource server.

Authorize a Client to Access a Resource Server

To manage a list of authorized clients, register the resource server in the “API” section of the admin console, as shown here.

API Configuration Settings

Include the “token” Response Type (Implict Flow Only)

If the client application is authenticating with LS-Auth using the OIDC Implicit Flow, you must include “token” among the response types selected in the application settings in the admin console. To request an ID token as well as an access token, specify “id_token token”. Note that applications using the preferred OIDC Authorization Code Flow do not need this setting.

Configure the Audience in a Client Application

If your client is using the Auth Service from the labshare/ngx-core-services package, follow the configuration guidelines in the README.md document.

Specifically, in the configuration, set the services.auth.audience value to the identifier URI of the resource server. This will be passed as the value of the “resource” parameter when requesting an access token from auth (either from the token endpoint or in an authorization request). If the application is authorized for the resource, the value will be included in the “aud” (audience) claim in the JWT.

Example client app configuration

{
	"services": {
		"auth": {
			"responseType": "code",
			"url": "https://myauthserver.org",
			"clientId": "my-client",
			"tenant": "my-tenant",
			"redirectUrl": "https://somehost.org/myclient",
			"postLogoutRedirectUrl": "https://somehost.org/myclient/loggedOff",
			"audience": "http://someresourceserver.org/api"
		}
	}
}

Other OIDC client libraries may refer to this setting as “resource”. Be sure to check the documentation. If you are constructing your own OIDC calls from scratch, you will add a parameter like “resource=http://someresourceserver.org/api” to authorization requests and/or token endpoint requests.