Topics on this page

Use BriteAuth to authenticate via single sign-on with BriteCore as the identity provider

BriteAuth is a centralized user identity management service that supports single sign-on (SSO) for your entire suite of internal and external apps.

Identity federation is a feature that allows users to sign in from your portal to BriteCore using BriteAuth without having to create a new username and password combination. This is commonly seen in other places in the form of Facebook Sign-In or Google Sign-In.

SSO provides a centralized place to manage users, in which user information and authentication data is automatically copied, or federated, to other systems.

BriteAuth supports identity federation using leading open protocols such as SAML 2.0 and OpenID Connect. In addition, Cognito and AWS IAM power the services and functionality provided by BriteAuth.

Key concepts

  • Authentication: Authentication validates a user’s identity.
  • Cognito: Amazon Cognito service provides APIs and infrastructure for key features in the user management space, including authentication, authorization, and user repository management.
  • SAML providers: Many enterprises operate internal user directories or authentication services. These services communicate via Security Assertion Markup Language (SAML). SAML is an open standard for exchanging authentication and authorization data between parties, particularly between an identity provider and a service provider. SAML support allows us to operate seamlessly with existing enterprise user directories such as Microsoft Active Directory Service.
  • Single sign-on (SSO): SSO is the practice of passing authentication along to a remote system, bypassing the need to log in to remote systems independently. In addition to passing tokens internally to BriteCore services, it can also pass them externally.
  • Tokens: The access token is passed to each individual service in BriteCore, ensuring the user’s identity is valid. If the token is revoked or tampered with, it will fail validation, logging the user out of all distributed services simultaneously.
  • User groups: User groups allow users to belong to a common classification. User groups can be used to trigger rules, manage access, or define associations. User groups are only accessible by administrators within BriteAuth. In the future, user groups will be used to control broader system access.
  • User pools: User pools are collections of users.
    • Internal: BriteAuth creates and manages an independent user pool for each BriteCore client along with a centralized user pool for BriteCore team members, allowing employees to manage a single profile across all client sites.
    • Federated Identities: Federated Identities link remote user identities to the internal BriteAuth identity.
    • Social Identity Providers: Authentication within several large social media services such as Facebook, Google, and Amazon are widely trusted across the internet. BriteAuth supports identities validated through these trusted authorities. This association allows us to support the very popular Log In with Facebook or Log In with Google options in BriteCore.
  • User profile: Each user in the system has user identity with an associated profile containing details about the user. User profiles include fields such as username, password, timezone, legal name, etc.

Standard OAuth2 authorization flow

The OAuth 2.0 authorization framework delegates access to APIs (HTTP resources) involving clients (such as your portal) that request scopes that resource owners (in this case, BriteCore) authorize/give consent to.

OAuth introduces an authorization layer that separates the role of a client from a resource owner. Instead of sharing password data, OAuth uses access tokens to verify a client’s identity. Access tokens are strings denoting a specific scope, lifetime, and other access attributes. The client uses the access token to access the protected resources hosted by the resource server.

Figure 1: Standard OAuth2 authorization flow.

 

Figure 2: Security interactions between a custom UI and BriteCore.

 

Figure 3: Security interactions between BriteCore and a third-party vendor.

 

Use BriteAuth to authenticate via single sign-on

Step 1: Request OAuth2 Client

Request a custom OAuth2 app client that will specify callback and sign out URLs.

By default, we will use Britecore as the identity provider, but it’s possible to use an external source for this.

Step 2: Redirect user sign-in URL

Note: Blocks of code are hidden by default to make the page more navigable. Select View code and Hide code to view or hide these sections as needed.

View code
GET 
https://<client>.britecore.com/api/auth/oauth2/authorize?
response_type=code&client_id=YOUR_APP_CLIENT_ID&redirect_uri=YOUR_REDIRECT_URL&state=STATE&scope=openid+profile

This can be done through a button, JavaScript, or through a server redirect response. Make sure YOUR_REDIRECT_URL exactly matches the one on file.

Step 3: BriteCore Log In screen

BriteCore will present a log in screen if the user isn’t logged in yet. After logging in (or if they’re already logged in), the user’s browser will be redirected to the following URL:

View code
GET 
YOUR_REDIRECT_URL?code=AUTHORIZATION_CODE&state=STATE

Note: YOUR_REDIRECT_URL must include the https:// portion.

Step 4: Obtain a valid access token from BriteCore

In your portal, read the authorization code from the code parameter (either in the backend or the UI) and use it to obtain a valid access token by calling the token endpoint:

Sample request

View code
POST https://<client>.britecore.com/api/auth/oauth2/token
Content-Type='application/x-www-form-urlencoded'
grant_type=authorization_code
client_id=YOUR_APP_CLIENT_ID
code=AUTHORIZATION_CODE

Sample response

The response will include the access token for the user:

View code
HTTP/1.1 200 OK
Content-Type: application/json
{ 
 "access_token":"eyJz9sdfsdfsdfsd", 
 "refresh_token":"dn43ud8uj32nk2je", 
 "id_token":"dmcxd329ujdmkemkd349r",
 "token_type":"Bearer", 
 "expires_in":3600
}

Step 5: Include the access token on all calls to BriteCore

Sample request

View code
GET https://client.britecore.com/api/user-management/users
Authorization: Bearer eyJz9sdfsdfsdfsd

You have successfully connected your portal to your BriteCore data.