Authenticate via Single-Sign-On (SSO)

BriteCore Authentication 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 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 are automatically copied, or federated, to other systems. Authentication 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 BriteCore Authentication.

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 trigger rules, manage access, or define associations. User groups are only accessible by administrators within Authentication. In the future, user groups will be used to control broader system access.
• User pools: User pools are collections of users.
  • Internal: Authentication 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 Authentication identity.
  • Social Identity Providers: Authentication within several large social media services such as Facebook, Google, and Amazon are widely trusted across the internet. Authentication 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 a 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. 

Authenticate via single sign-on

Step 1: Get a security token

You will need to request an ID and Secret to use OAuth 2.0.

For more information, refer to How do I get started?

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

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 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 login 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: 

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

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: 

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

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

You have successfully connected your portal to your BriteCore data.