Skip to main content

OIDC Trusted Identities

Authress enables you to connect any Authentication provider from anywhere to your Authress account. This provides power cross account security opportunities as well as deep integration with third party tools. Many tools generate their own tokens, and rather than needing them to understand how to connect to Authress or generating Authress Service Clients, you can directly enable trust for these providers. These providers are usually CI/CD such as GitHub or GitLab or may be an existing Authentication solution you already have, and even another Authress account (in the case of non-production usage).

In many cases, these tokens or key signatures are already trusted by your platform. To have Authress trust them as well, add a new OIDC Trusted Identity.

How does it work?​

OIDC compliant JWTs contain an iss claim in the JWT. Authress registers this iss and the aud of the token with your account. When a token is received by Authress during normal authorization checks or access record creation, the token is then verified using your configuration. If it is a valid token, then the user represented by that token (in the sub claim) is treated as if that token was generated by Authress itself.

Identity Provider Connections versus OIDC Trusted Identities​

OIDC trusted identities enable integrating your Authress account with an existing authentication mechanism. You can allow these other providers to directly control and let their users log into and manage your Authress account. Other providers and platforms create JWT identity tokens--such as a Cloud Provider, a CI/CD pipeline job, or another IdP--and can be directly linked.

The difference between providers here and the Connections specified in the above login sections is the following:

  • Summary: Use this Authress account as your Login Provider
  • Connections are how your users log in to your application
  • Authress converts those connections to a unified experience for your applications
  • Incoming JWTs from the providers are converted to a standardized Authress login token
  • These tokens are used by your applications and services for authentication and authorization
  • Users will get an Authress userId and roles are assigned to these userIds

Compared with OIDC trusted identities:

  • Summary: Use your existing Login Provider to authorize api calls to Authress
  • A third party platform or another Authress account already has created a token or API key
  • You want your Authress account to trust these tokens as if they were Authress JWTs from this account
  • In some cases these might have been generated by a CI/CD Pipeline
  • In other cases they might have been generated by your Identity or Authentication Provider when not using Authress
  • Authress uses these tokens as is, no additional tokens are generated
  • You assign Authress roles to userIds generated by these providers
  • You want to authentication to Authress using these tokens instead of using a Service Client API Key

Configuring a new Trusted Identity​

Navigate to the Connections configuration in Authress and scroll down to OIDC Trusted Identities and click Add trusted provider

OIDC Trusted identities

And then enter an existing JWT from that platform.

How to register your auth provider with Authress

Customizing the configuration​

It's possible that you have JWTs that are not OAuth2 compliant. While unfortunate, Authress still needs to be able to support them as well. In the configuration for the trusted identity, any claim or property in the JWT can be used to signify where the user ID actually is. By default this is set to be the {sub} claim, which is the standard in OAuth2.0. However, for example, if you have a JWT that looks something like this:

Decoced JWT
{
        "iss": "https://login.authress.io",
        "sub": "user_id",
        "team": "team_id",
        "alt_sub": "user_id_alternate"
}

You can configure Authress to use the custom property with the key that matches with your needs instead. To do this, find the User ID Expression property and enter the appropriate value. For instance, if we wanted to use the alt_sub instead of the sub, you would enter {alt_sub}.

Decoced JWT with deeply nested claim
{
        "iss": "https://login.authress.io",
        "sub": "user_id",
        "team": "team_id",
        "additional_claims": {
                    "other": "user_id_alt_2"
        }
}

The expression handler also supports complex expressions and nested hierarchies, for example, you could have {team}|{additional_claims.other}, where multiple replacements are included and deeply nested values.

One last example might include the complex uri found in the JWT. This too is supported: {https://company.domain.com/claims.property}.

Decoced JWT with complex URI
{
        "iss": "https://login.authress.io",
        "sub": "user_id",
        "https://company.domain.com/claims": {
                    "property": "user_id_legacy"
        }
}

Customized User ID EXpression

Configuring an identity without a JWT​

Authress uses JWTs to verify that the configuration is correct, because registering a token here enables tokens generated by that source to be granted the permissions you have configured in your account. However in some cases, it might not be possible to procure a valid JWT representing that external system. In those cases, click the I don't have access to a token link, and fill out the values manually:

No access to JWT

Manually link JWT provider