EN globe icon
user icon
On This Page
What can we help you find? Products Total Spend Management Platform Integration Technical Documentation The Coupa Core API OAuth 2.0 and OIDC OpenID Connect Clients

OpenID Connect Clients

Use OpenID Connect (OIDC) to provide additional security that's beyond traditional API keys.

OIDC is a way of authenticating clients using OAuth 2.0 when they connect to Coupa. For more information, see OpenID Connect.

OAuth 2.0 clients

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.

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.

Client credentials grant type

Use the client credentials grant type when there is no user involved, such as in system-to-system integrations. The token is automatically accepted and generated.

Example client credential cURL request

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

Authorization code grant type

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

User flow

  1. 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>

  2. Click Allow on the consent screen. The application redirects to REDIRECT_URI specified when you created the client.

To retrieve the access token with the code, make an HTTPS POST request . Below is an example of a request using cURL:

Example authorization code cURL request

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>

Device code grant type

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.

Example device code cURL request

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

The JSON response contains 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.

  • Tokens are provided in JWT format. 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.

Related webinars