Skip to main content

Using OpenID Connect with XXID

Note:

This functionality is currently experimental and subject to change.

You may want to connect other applications to XXID using OpenID Connect. This may occur when you want users to be able to log in to you Grexx environments as well as other non-Grexx client applications within your ecosystem. This article provides a basic example of how to configure your client application to use XXID as an SSO provider using node.js and Typescript. When using the technology of your choice, please refer to the appropriate documentation of that framework.

Set up your OpenID Connect client​

To set up your OpenID Connect client, you first need to install the openid-client library and configure it with your client credentials.

If you want to configure XXID to display branded designs for login and logout flows, you will need to set your client_id as your Grexx brand ID. You will also need to provide a client secret and a list of valid redirect_uris to which XXID can redirect an authenticated user.

import { Issuer } from 'openid-client';

const discoveryUrl = 'https://xxid.grexx.today/';
const discovered = await Issuer.discover(oidcUrl);
const client = new discovered.Client({
            client_id: config.oidc.clientId,
            client_secret: config.oidc.clientSecret,
            redirect_uris: config.oidc.redirectUris,
            response_types: ['code'],
});

Redirect unauthorized users to the authorization URL​

To redirect unauthorized users to the authorization URL, you need to generate a code verifier and challenge, and then construct the authorization URL.

import { generators } from 'openid-client';

const codeVerifier = generators.codeVerifier();

const code_challenge = generators.codeChallenge(codeVerifier);

const authUrl = client.authorizationUrl({
            scope: 'openid email profile',
            code_challenge,
            code_challenge_method: 'S256',
});

// You can now redirect to the auth URL

Set up your callback endpoint to exchange tokens​

Once users are authenticated, they are redirected to your application with an authorization code. You need to exchange this code for tokens.

    async getAuthenticatedUserInfo(req): Promise<{ userInfo: UserInfo<any>; tokenSet: TokenSet }> {
        const params = this.client.callbackParams(req);
        try {
            const tokenSet = await this.client.callback('https://example.com/auth/callback', params, {
                code_verifier: req.session?.code_verifier, // The code verifier generated earlier
            });
            return tokenSet.access_token
                ? { userInfo: await this.client.userinfo(tokenSet.access_token), tokenSet }
                : null;
        } catch (e) {
            const message = 'Error getting user info: ' + e.toString();
            throw new Error(message);
        }
    }

Log out the user​

To log out a user, you can redirect them to the endSessionUrl. If you want to display a branded logout page, include the brand in the query parameter.

client.endSessionUrl({
   id_token_hint: tokenSet.id_token,
});