Skip to main content

OAuth setup guide - Part 2

For most OAuth provider connections, the provider follows the current RFC standards, such as RFC 9068. For these, Authress automatically discovers the configuration and verifies incoming users without any additional setup. However, some OAuth providers do not use JWTs or don't follow RFC standards for access tokens exchange. Because of the lack of standard compliance, custom configuration is necessary.

Validating a provider and testing a connection​

To determine if a provider is following the standard, or for the validation of any configuration, Authress suggests using the Test Connection button in the connection configuration.

OAuth test connection button

This opens a new tab to start the login flow. Because there aren't any existing standards on how to represent errors, it's possible to get back any number of problems shown via url query parameters, blank pages, or text on a white pages. If the connection configuration is partially correct, a user will get navigated to a dedicated Authress detailed information page to explain the current error.

Common errors​

Invalid scopes listed​

Occasionally, some OAuth providers have custom requirements on the scopes allowed to be requested and used. By the RFC spec, when incorrect scopes are specified they should be ignored. However, a provider may choose to return an error instead. This coupled with the fact they might not allow the standard default scopes of openid profile email, causes errors. In these cases, scopes can be specified either in the Authress Login SDK using the connectionProperties configuration or by setting them for all login calls in the Default Scopes section of the connection configuration:

Non standard OAuth scopes

Specify replacement scopes for the connection, or in the case that no scopes are allowed or required, remove the default values and leave empty.

Connection provider is not OpenID compliant​

If the tokens that are received by Authress from the configured provider do not contain the required information this error will be displayed.

connectionProviderIsNotOpenIdCompliantError.json
{
  "errorCode": "ConnectionProviderIsNotOpenIdCompliant",
  "title": "The connection configuration is incomplete.",
  "connectionId": "o5X9NJcGh6rHKqfZ7YpEHp",
  "oidcUserEndpointUrl": null,
  "expressionSourceData": {
    "application_id": "b8a49f3399815cedd110f0fcedd7f0b9745fde77a9b97ab262c60cfbba18fdcc",
    "uid": "arqzx123"
  }
}

The problem is that by default, Authress will look for the sub property of the JWT id_token. If the sub claim does not exist or the token is not a JWT, then the connection needs to be configured to specify how to calculate the sub.

The sub claim represents a globally unique userId in the provider's platform. Without this information, there is no way to tell two users apart or correlate the identity of the user logged in with their data. The solution is to pick an existing claim shown in the expressionSourceData property from the error. This always works, however in rare circumstances based on the provider, this can be brittle. So, before selecting arbitrary values from this token, confer with the connection provider's documentation on how to globally identify users.

In the case of the example there is a property uid, so if the provider acknowledges that is the right property, set the User ID Expression in the connection configuration:

Non standard OAuth token claims

Some providers insist that their tokens should not be inspected, and therefore instead it makes sense to find and add the url endpoint where the unique userId can be found. Authress will automatically look up data from this endpoint to allow userId resolution. For instance, if the user data can be found at:

https://api.custom-provider.com/oauth/user-data/endpoint

Then, specify it in the OIDC User Data Url:

Non standard OAuth token data url

User ID expression and data mismatch​

Check the expression used and the error message for more information, most cases this indicates that the expression selected, in this case {invalid-property} isn't present in the expressionSourceData, it should be data.userId:

userIdExpressionAndDataMismatchError.json
{
  "errorCode": "UserIdExpressionAndDataMismatch",
  "title": "The connection configuration is incomplete.",
  "connectionId": "o5X9NJcGh6rHKqfZ7YpEHp",
  "oidcUserEndpointUrl": "https://api.custom-provider.com/oauth/user-data/endpoint",
  "userIdExpression": "{invalid-property}",
  "expressionSourceData": {
    "data": {
      "userId": "user_111",
      "email": "user_111@authress.io"
    }
  }
}

Login success​

And when it all works the result should be a Login successful information page:

Successful OAuth login

Preferred connection configuration​

In a lot of scenarios, especially with non-standard OAuth providers, Authress already contains pre-configured connections. These have all the right properties set and can be used out of the box. To copy the working pre-configured connections, the connection configuration for these pre-configured connections contain a Clone button. This will create a new connection with all the correct properties populated and can save a lot of time perusing documentation. In the case that a pre-configuration connection does not exist for your provider, and it is an OAuth provider, reach out support@authress.io, and we'll add it.

cloning an OAuth configuration

Non-OAuth identity providers​

In the case you are running an internal identity provider that isn't OAuth compliant or doesn't use asymmetric public key signatures, follow the advanced Non-OAuth setup guide - part 3.