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 are 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 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 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. 
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.
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.