Single Sign-On with AWS Cognito

If your users already sign in to your own product through an Amazon Cognito user pool, they can sign in to ClaimRev with the same account. ClaimRev connects to Cognito as an OpenID Connect (OIDC) identity provider: when one of your users signs in to ClaimRev, they are sent to Cognito, sign in there, and come back signed in. When you disable someone in Cognito, their ClaimRev access ends too.

You set this up yourself in the portal, and ClaimRev approves it before it is turned on.

What ClaimRev single sign-on covers today

• Users on your email domain. Single sign-on applies to users whose email address is on your domain (the part after the @, for example yourcompany.com), once you have verified that domain. Users who belong to other ClaimRev accounts as well, such as an outside biller, keep their own sign-in.
• The account you set it up on. If you run child accounts for practices whose staff use other email domains, talk to ClaimRev before you start: single sign-on for a whole family of accounts is set up with us, not through the steps below.

What you need

• Access to the AWS console for the user pool.
• In ClaimRev, a portal role with access to Practice Admin, then Identity & Access, then Single Sign-On (SSO). If you do not see it, ask your practice administrator or ClaimRev support.
• Every user who will sign in this way must have the same email address in Cognito as in ClaimRev, and it should be verified in Cognito. ClaimRev matches people by email address.

Test and production are separate. Set up single sign-on in testportal.claimrev.com first, check it works, and then repeat these steps in the production portal with a production app client.

1. Give your user pool a domain

Cognito's sign-in endpoints only exist once the user pool has a domain (a Cognito domain such as yourcompany.auth.us-east-1.amazoncognito.com, or your own custom domain). If your user pool already uses managed login (the hosted UI), it has one. Otherwise add one under the user pool's Domain settings.

2. Create an app client for ClaimRev

In the user pool, create a new app client just for ClaimRev:

1. Application type: choose Traditional web application. This creates a client secret, which ClaimRev needs. A client secret cannot be added to an existing app client later, so create a new one rather than reusing a public client.

2. Name: anything that tells you what it is, for example ClaimRev.

3. Allowed callback URL (Cognito may call it the return URL): ClaimRev's sign-in callback.

   Portal	Callback URL
   Test (testportal.claimrev.com)	https://auth-staging.claimrev.com/idps/callback
   Production	https://auth.claimrev.com/idps/callback

   The ClaimRev SSO page shows the exact URL to copy, under Before you start.

4. OAuth grant type: Authorization code grant only.

5. OpenID Connect scopes: openid, email and profile. Without email, ClaimRev cannot tell who has signed in.

6. Identity providers for the app client: Cognito user pool (your own users), plus any other identity providers your users sign in through in Cognito.

Then note three values from the app client and the user pool:

• Client ID and client secret of the app client.
• The issuer URL: https://cognito-idp.<region>.amazonaws.com/<user pool ID>, for example https://cognito-idp.us-east-1.amazonaws.com/us-east-1_AbCdEf123. You can check it by opening that URL with /.well-known/openid-configuration on the end.

3. Enter it in ClaimRev

In the portal, open Practice Admin, then Identity & Access, then Single Sign-On (SSO):

1. Provider type: choose Other OpenID Connect provider.
2. Issuer URL: the issuer URL from step 2 (no trailing /.well-known/...).
3. Client ID and Client secret: from your app client. The secret goes straight to ClaimRev's sign-in service and is never shown again.
4. Your email domain: the domain your users' email addresses are on.
5. Choose Set up single sign-on, then Request approval.

ClaimRev checks the details and turns it on. Changing the client ID or issuer after approval turns single sign-on off until ClaimRev approves the change; a new client secret does not.

4. Move your users and verify the domain

Once it is approved, the SSO page walks you through the rest:

1. Move your staff to single sign-on. Choose See who will move to check the list first. Everyone on your domain who belongs only to this account switches to signing in through Cognito.
2. Verify your domain. Choose Show DNS record, add the TXT record to your domain's DNS, then choose Check DNS record. Do this after your staff are on single sign-on. New users on your domain then go straight to Cognito, with no ClaimRev invitation email.

Troubleshooting

What happens	Likely cause
Cognito shows redirect_mismatch	The callback URL in the app client does not exactly match the one for that portal (test and production differ).
Cognito sign-in works, then ClaimRev says it cannot sign you in	The user's email in Cognito does not match their ClaimRev email, is not verified, or the email scope is missing from the app client.
ClaimRev cannot reach the issuer	The issuer URL is wrong, or includes /.well-known/openid-configuration. Enter only https://cognito-idp.<region>.amazonaws.com/<user pool ID>.
Sign-in fails right after Cognito with an "invalid client" error	The client secret is wrong, or the app client was created without one. Create a new app client of type Traditional web application and enter its secret.

Amazon's own documentation for these settings: app clients and user pool endpoints.