Connect an API that uses Amazon Cognito

If your API verifies access tokens issued by an Amazon Cognito user pool, Faustine signs in as an app client of that pool, with the client credentials grant. You create the app client in Cognito and enter its values in Faustine.

Before you begin

The user pool has a domain. The token endpoint is served from it.
The user pool has a resource server for your API with at least one custom scope. Cognito issues client credentials tokens only for resource server scopes.

Create the app client in Cognito

In the user pool, create an app client for Faustine that has a client secret and allows the client credentials grant, and allow it the custom scopes of your API's resource server. For the screens, see Scopes, M2M, and resource servers and The token endpoint in the Amazon Cognito documentation.

Note four values: the user pool's domain, the scopes, and the app client's ID and secret.

Set the token endpoint on the API

In the portal, go to APIs and select your API.
Select the Authentication tab, then Edit.
In Sign-in method, select OAuth client.
In Token provider, select Amazon Cognito. Client secret sent changes to HTTP Basic.
In User pool domain, enter the pool's domain, such as acme.auth.us-east-1.amazoncognito.com.
In Scopes, enter the scopes to request, separated by spaces. Each one is written <RESOURCE_SERVER_ID>/<SCOPE>, such as nimbus-api/read nimbus-api/write.
Leave Audience empty.
Select Save changes.

The token URL appears under User pool domain:

https://<USER_POOL_DOMAIN>/oauth2/token

A custom domain works in User pool domain too. The next time you open the form, it shows the provider as Custom with the same token URL.

Add the client to a connection

Select the Connections tab, then New connection, or select an existing connection.
In Credentials, enter the Client ID and Client secret.
In the Test step, select a read operation and select Test connection.

Reached the endpoint with a 2xx status confirms that Cognito issued a token and your API accepted it.

Troubleshooting

Symptom	Cause	Fix
`Identity provider refused the client credentials`, with `invalid_client`	The client ID or secret is wrong, or the app client has no secret.	Correct the values in the connection. Use an app client that has a secret.
`Identity provider refused the client credentials`, with `invalid_scope`	A scope is not written as `<RESOURCE_SERVER_ID>/<SCOPE>`, or the app client is not allowed it.	Correct Scopes, or allow the scope for the app client.
`Identity provider refused the client credentials`, with `unauthorized_client`	The app client does not allow the client credentials grant.	Allow the grant for the app client.

Next steps

Connect with an OAuth client: every field of the strategy and how the token is renewed.
Add a connection: the full wizard.
Authentication: the other strategies.