This tutorial shows how to configure an Identity Provider (IdP) within Aurora so users can take advantage of single sign-on (SSO).

How It Works

With SSO, users will no longer need to sign in using an Aurora login. Instead, they can sign in to their IdP with credentials they are already familiar with.

Getting Started

To complete this tutorial, you will need:

• your Aurora tenant to be on Custom plan
• your Aurora bearer token and tenant_id that you or any Administrator for your Aurora tenant can retrieve from the API Settings
• an IdP that supports the OpenID Connect protocol (e.g. Salesforce, Okta, Duo Security)
• an app created for Aurora in your IdP
• The following parameters from your Aurora IdP app:
  • openid_discovery_doc_url: A URL to the discovery document, a JSON object containing information about the IdP. It must have a field called jwks_uri.
  • openid_key and openid_secret: The credentials Aurora needs to communicate with the IdP. These are sensitive and should be kept secure. Sometimes called Client ID and Client Secret or Consumer Key and Consumer Secret.
  • auth_uri: The authorization URI that Aurora will redirect to where users sign in and grant permissions, if necessary. Can be found in the discovery document
  • token_uri: The URI that Aurora will call to get the access and id tokens once the user is signed in to the IdP. Can be found in the discovery document

Step 1. Create the SSO Provider in Aurora

Create the identity provider for your tenant

//POST https://api-sandbox.aurorasolar.com/v2/tenants/{tenant_id}/sso_provider

{
     "sso_provider": {
			 "auth_uri": "https://login.foobar-sso-provider.com/services/oauth2/authorize",
	     "token_uri": "https://login.foobar-sso-provider.com/services/oauth2/token",
	     "openid_key": "123",
	     "openid_secret": "abcde",
	     "openid_discovery_doc_url": "https://login.foobar-sso-provider.com/services/oauth2/.well-known/openid-configuration"
     }
}

//HTTP 200 Response
{
     "sso_provider": {
			 "provider": "aurora_solar",
			 "auth_uri": "https://login.foobar-sso-provider.com/services/oauth2/authorize",
	     "token_uri": "https://login.foobar-sso-provider.com/services/oauth2/token",
	     "openid_key": "123",
	     "openid_secret": "abcde",
	     "openid_discovery_doc_url": "https://login.foobar-sso-provider.com/services/oauth2/.well-known/openid-configuration",
		   "openid_base_url": "https://sandbox.aurorasolar.com/auth/openid/aurora_solar",
		   "openid_callback_url": "https://sandbox.aurorasolar.com/auth/openid/aurora_solar/callback"
		 }
}

Step 2. Configure your identity provider

Most IdPs will require you to allow certain callback URLs. You can add the openid_callback_url to your identity provider so it will correctly redirect to Aurora after a user has logged in.

The openid_base_url is what you will use to construct any links into Aurora using a redirect, e.g. https://sandbox.aurorasolar.com/auth/openid/aurora_solar?redirect_uri=https://v2-sandbox.aurorasolar.com/projects is an SSO-enabled link to the project index page.

The “aurora_solar” part of the urls will be different and unique to your tenant.

Step 3. Create users

By using the Create User API and specifying the external_provider_id field, you will link the id of the user in Aurora to the id of the user in your IdP. If this is not done and a user attempts to log in, they will receive an error message containing the IdP’s identifier for them.

//POST https://api-sandbox.aurorasolar.com/v2/tenants/{tenant_id}/users
{
     "user": {
          "first_name": "Jerry",
          "last_name": "Seinfield",
          "email": "[email protected]",
          "phone": "(415) 360-9291",
          "title": "Solar Account Executive",
          "external_provider_id": "https://test.salesforce.com/id/00556000000X3J3AFA/00540000001ulvMAEA",
          "user_level": "Team Member"
     }
}

Once a user is created with the correct id, they will be able to log in to Aurora using an SSO link, like the one in Step 2.