What can we help you find? Products Platform Integration Technical Documentation The Coupa Core API OAuth 2.0 and OIDC OpenID Connect Clients

OpenID Connect Clients

Use Open Connect to provide additional security that's beyond traditional API keys.

OpenID Connect is a way of authenticating clients when they connect to another service. OpenID Connect uses public-key-encryption-based authentication to increase the security of your connection to Coupa. In fact, creating and managing clients is easy when connecting with Coupa.

How it works

When you create a new Open Connect client, you're granting access to a specific application or user client for specific areas of the product, defined by scopes. Once you create the client in Coupa, use the application or client to request an access token based on the grant type you specify.

Step 1: Create a client in Coupa

You can create, activate, or deactivate individual clients from the OpenIDConnect Clients table by going to Setup > Integrations > Oauth2/OpenID Connect Clients .

Setting	Details
Grant type	Client credentials: Used when there is no user involved. Typically used for system-to-system integrations. (Most common) Authorization code: Used when an end user is involved and requires the user's consent before granting an access token to be used to access resources. Device code: Used in cases where the client resides on a device and the user gets authenticated and authorizes the request on another.
Name	Name of the client/application
Redirect URIs	A redirection URI where the response will be sent.
Scopes	When a customer registers a client they have to assign scopes to the client. Scopes are required and determines what the client/application is allowed to do.

Scopes

Coupa scopes take the form of service.object.right. For example, core.accounting.read or core.accounting.write. There are a handful of scopes listed today on the client create/edit page. You can find the list of scopes and their underlying Coupa permissions by going to the Scope management page at /oauth2/scopes. When you drill down into a scope, you can see the specific API permissions associated with that scope.

The list of Scopes and actions associated will continue to grow in two ways: more actions within each scope, and more scopes in general.

Step 2: Get an OpenID Connect access token

Once you've created a client, the next step is to request for an access token. Depending on what grant type you chose for your client, the request differs slightly.

Client credentials

Used when there is no user involved. Typically used for system-to-system integrations. Token is automatically accepted and generated (most common).

Client credentials requires no consent and a HTTPS POST request can be made directly to Coupa. Below is an example of a request for an access token using curl:

        curl -X POST -H "Content-Type: application/x-www-form-urlencoded" -d "client_id=<CLIENT_ID>&grant_type=client_credentials&scope=<SPACE_SEPARATED_LIST_OF_SCOPES>&client_secret=<CLIENT_SECRET>" https://<INSTANCE_DOMAIN>/oauth2/token

The response from the curl command will be JSON object that contains the access token using JWT format.

Note:

By design, there is no limit to the length of a JWT token. Tokens can become very long, partially dependent on the number of scopes supported by the token. Please plan your integration development accordingly.

Authorization code

Used when an end user is involved. Requires the user's consent before granting an access token to be used to access resources. Someone is manually accepting the token regeneration.

In a web browser, paste the following URL into the address bar (replacing the elements between brackets with the correct values).

        https://<INSTANCE_DOMAIN>/oauth2/authorizations/new?client_id=<CLIENT_ID>&response_type=code&scope=<SPACE_SEPARATED_LIST_OF_SCOPES>&redirect_uri=<REDIRECT_URI>

This will take you to the consent screen. Clicking Allow will then redirect you to the REDIRECT_URI specified when you created the client. The redirection will also contain a CODE in the redirected URI that will be used by the client to retrieve the access token.

To retrieve the access token with the code, a HTTPS POST request must be made. Below is an example of a request using curl:

        curl -XPOST -i https://<INSTANCE_DOMAIN>/oauth2/token?client_id=<CLIENT_ID>&grant_type=authorization_code&code=<CODE>&scope=<SPACE_SEPARATED_LIST_OF_SCOPES>&client_secret=<CLIENT_SECRET>&redirect_uri=<REDIRECT_URI>

The response from the curl command will be JSON object that contains the access token.

Device code

Used in cases where the client resides on a device and the user gets authenticated and authorizes the request on another. The device asks the user to go to a link on their computer or smartphone and authorize the device.

Device code requires a HTTPS POST request to be made. Below is an example of a request for an access token using curl:

        curl -XPOST -i https://<INSTANCE_DOMAIN>/oauth2/device_authorizations?client_id=<CLIENT_ID>&scope=<SPACE_SEPARATED_LIST_OF_SCOPES>

The curl request above will be a JSON response containing the verification_uri and user code among other values. Go to the verification_uri on a browser and enter the user code to complete the flow.

Design Considerations

When developing an integration, ensure that you include at least a five-second buffer in your code between when you generate a token and when you submit an API call using the token. Otherwise, the second call is submitted before the authentication token is generated and your call may fail.