Non-OAuth setup guide - Part 3

This guide details how to hook up an internally managed identity provider to Authress to enable consistent token generation. In the case you want to connect a public federated provider instead, follow one of these guides:

An internally managed identity provider usually exists in a legacy platform. You have some architecture today to verify users and generate user identity tokens. If these tokens are already OIDC compliant and are signed by an asymmetric algorithm, then you should follow the Connecting a non-standard public identity provider guide.

This avoids the need for your applications to interoperate between two types of tokens–the ones that Authress generates, and the ones being generated by your legacy identity provider.

Background: The Authress login flow

The standard Authress login flow, starts in your web app. The user requests to login, which generates a login request using one of your configured Authress connections. The connectionId and applicationId are passed to the login SDK. This is the same flow your application is already using to login with Authress, and it will be reused for your legacy identity provider, so no changes are necessary to your web app. As a reminder these are the relevant SDK methods:

1. Linking your identity provider

To link the identity provider to Authress, a new special kind of connection will be created. This connection treats your existing identity provider with advanced permissions allowing it to request Authress identity tokens.

Generate a new Authress Service Client. Enter a name for the client, and select the option to Grant the client OAuth user impersonation. This allows this client to directly communicate with the Authress login API to request user identity tokens.

Enable the legacy authorization service

2. Enter your legacy identity provider URL

Your identity provider has a UI associated with identifying the user. This may be a username/password prompt or an email prompt requesting the user’s email for a magic login token based flow. Set the Authorization Url to be this URL.

Create a legacy authress connection

At this point, it is recommended that you click Test Connection to ensure that the redirect to your identity provider is correct.

3. User agent flow

When the user client logs in and the Authress Login SDK is invoked via the loginClient.authenticate() method, the user will be redirected to the specific URL from #2 above. They’ll being the flow, whatever this may be. In the case of username/password or a magic token, you’ll use the existing logic to direct and navigate the user to the appropriate location. The result of their interactions must be a request to your existing identity service:

  • In the case of username/password, send the username and password to your identity service. The identity service should verify the user’s credentials and then generate an Authress assertion to continue the login process.
  • In the case of a magic token, the user should be directed to retrieve the token, and then redirected back your identity UI. The UI should pass the token to your identity service to be verified. Once verified, the service will then generate an Authress assertion to continue the login process.

Important: Authress will send a state parameter to your Authorization URL. This state parameter must be passed back to Authress in the next step. This token is not sensitive and should not be treated as a replacement for a secure identity.

4. Generating the Authress Assertion

Once the user’s identity has been verified, the identity service is ready to hand-off the user to Authress to complete the login flow. This can be done using the generateUserLoginUrl() method from one of the Authress SDKs, which creates the Authress assertion and redirect url. (Note: this happens inside the identity service, not in the user’s UI)

5. User completes the login flow

Step #4 generates an assertion in the form of a URL. This URL should be sent back to your user, in the form of a browser redirect. The user will be directed to Authress to complete the assertion, and then will be logged in with an Authress identity token. The token and user will be sent back to the origin application url that started the process.

Didn't find what you were looking for?

Or send us an email at