Table of contents

Get access to the API

After a successful CustomerID installation or upgrade eIDM Services site has CustomerID API application visible in SSO Management UI.  The API is accessible using OAuth2 to a group named CustomerID API Users. In order to access the API, a new OAuth2 application must be created and an API user needs to be defined. The following steps will guide you through these steps.

Creating a new OAuth2 application

Create new OAuth2 client application as instructed in Management UI Applications or alternatively use the Management API. Allow CustomerID API Users to access the newly created application and enable for example password.2 method or your preferred method for the application.

{
  "client_id": "... redacted ...",
  "client_secret": "..redacted..."
}

After the application has been configured proceed with defining an API user.

Define API user

Add a user to CustomerID API Users group e.g. with the Management UI. You can choose from the following options:

• Create a new user with password.2 method allowed, and add it
• Add an existing user with password.2 method allowed
• Add an existing group

Any of these actions can also be performed using the Management API. 

Locate API scope

In order to access the CustomerID API you need its client ID for the scope parameter of the OAuth2 Token Request. This client ID has been defined in your linux/win32.config file with setting: rest.oauth2.client.uuid and is visible in eIDM Services → Applications → CustomerID API as depicted here

Add SSO server certificate to Java trust store

When using OAuth2 access token CustomerID API connects to the SSO OAuth 2.0 endpoints, so the server certificate of those endpoints must be trusted by the Java Runtime Environment used by CustomerID. By default, no publicly issued CAs are trusted and must be trusted explicitly.

Follow these steps on each CustomerID node by applying the instructions from here:  Add Server Certificate to Java Trust Store - SSO

• When SSO is installed on different server than CustomerID copy the SSO certificate file to the CustomerID server
• Add certificate to Java trust store and
• Restart CustomerID i.e. WildFly

Verify the API works

The following examples use the REQ003 List Organizations API call documented in REST API 2.0 - CustomerID.

Test the connection

You can start testing the connection using curl. You may use the --insecure flag in case self-signed certificates are used:

$ curl --request GET 'https://<customerid-base-url>/customerid-rest/services/2.0/organizations?technicalName=not-found'

An HTTP 401 status code is expected as no OAuth2 access token was provided in the request. The response will contain WWW-Authenticate header with the required scope for the SSO OAuth2 token endpoint.

Get the access token

Different SSO endpoints for OAuth2 and how to find them are explained in OAuth 2.0 and OpenID Connect metadata.

Get the access token e.g. with OAuth2 Password grant:

$ curl \
  --request POST 'https://<sso-base-url>/uas/oauth2/token' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'grant_type=password' \
  --data-urlencode 'scope=openid <customerid-api-client-id>' \
  --data-urlencode 'client_id=<oauth2-client-id>' \
  --data-urlencode 'client_secret=<oauth2-client-secret>' \
  --data-urlencode 'username=<customerid-api-user>' \
  --data-urlencode 'password=<customerid-api-password>'

Where

customerid-api-client-id

oauth2-client-id

oauth2-client-secret

customerid-api-user

customerid-api-user-password

Use the access token

Take the access token from the response and use in the CustomerID API request:

$ curl \
  --request POST 'https://<customerid-base-url>/customerid-rest/services/2.0/organizations?technicalName=not-found' \
  --header 'Authorization: Bearer <your access token here>'

As a valid OAuth2 access token was provided, the expected status code is HTTP 200 with a similar response body:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<Organizations xmlns="http://schema.ubisecure.com/customerid/api" inResponseTo="/2.0/organizations/" method="GET"/>

This indicates that the request was authorized and it returned an empty list of organization IDs assuming there is no organization with the technical name not-found.

Troubleshooting

eIDM Services → Applications → CustomerID API application not found

You have not imported the new versions of customerid.ldif and customerid-secrets.ldif including OAuth2 entries to the LDAP repository.  

Check that you have proper settings in linux/win32.config for the following properties:

rest.oauth2.client.uuid
rest.oauth2.client.secret
rest.oauth2.introspection.url

and if you change the client credentials rerun setup script and restart CustomerID i.e. WildFly first before importing the LDIF files.

OAuth2 authentication challenge is not returned when accessing API without access token

If in step Test the connection HTTP 403 is returned instead of the expected HTTP 401 with the following error response:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<error>
    <code>2</code>
    <message>Invalid credentials</message>
</error>

OAuth2 authentication is not enabled in your CustomerID configuration.

Check that you have proper settings in linux/win32.config for the following properties:

rest.oauth2.client.uuid
rest.oauth2.client.secret
rest.oauth2.introspection.url

rerun setup script and restart CustomerID i.e. WildFly. If you changed the client credentials you need to import customerid-secrets.ldif again to the LDAP repository.

Getting access token fails

If in step Get the access token HTTP 400 is returned instead of the expected HTTP 200 with the following error response:

{
    "error_description": "Client is invalid",
    "error": "unauthorized_client"
}

you have forgotten to enable the appropriate password method in step Creating a new OAuth2 application.

Tick from the SSO Management UI for the OAuth2 application you created e.g. password.2 method and click Update on below of the screen.

Using access token fails

If in step Use the access token HTTP 500 is returned instead of the expected HTTP 200 with the following error response:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<error>
    <code>6</code>
    <message>Token validation failed</message>
</error

the token introspection URL rest.oauth2.introspection.url you have specified in linux/win32.config is not valid. Do the following:

• Check you have completed step Add SSO server certificate to Java trust store on each CustomerID node
• Check the proper SSO token endpoint URL e.g. from the SSO metadata response
• Specify rest.oauth2.introspection.url in linux/win32.config accordingly

• Rerun the setup script and
• Restart CustomerID i.e. WildFly