SSO Integration Guide for I-9 Complete v2.0

Claims-Based Identification 

Claims-based identity is a straightforward idea, founded on a small number of concepts: claims, tokens, identity providers, and a few more. 

What is an identity? A digital identity is a set of information about somebody or something. It’s common to refer to a set of identity information as a security token or token. A token contains one or more claims, each of which carries some piece of information about the user it identifies.  

Identity Provider 

The software tool or service that performs the authentication, checking usernames and passwords, verifying account status, invoking two-factor, etc. Tokens are created by Identity Providers (IDPs).  

Service Provider

A Service Provider (SP) is a system entity that receives and accepts an authentication tokens issued by an identity provider. A web application that provides a service to its users. Tracker I-9 Complete is the service provider.  

Open Standard 

There are several standards-based authentication protocols: OpenID Connect, SAML 2.0 and OAuth 2.0. Tracker uses OpenID Connect protocol. OpenID Connect is an open standard that organizations use to authenticate users. IDPs use this so that users can sign in to the IDP, and then access other websites and apps without having to log in or share their sign-in information.  

Dynamic User Management 

In this scenario, you send a complete list of claims needed to create the user.  If the provided username does not exist in our system, we create a new user.  If the user does exist, the user is updated based on the information sent in the assertion.  As long as you are able to send a complete set of user claims, then no additional integrations or manual intervention is needed to manage user’s accounts. 

Authorization Only 

In this scenario, you send only one piece of information (username, email, or external id) to identify a user.  If this user exists in our system, we authenticate them and let them in.  If they do not exist, they are not given access to our application.  This approach is only recommended if you create and manage users via Tracker’s API. 

Hybrid 

In this scenario, you send a complete list of claims needed to create a user.  If the provided username does not exist in our system, we create a new user.  If they do exist, we let them have access to the system, but we do not update them.  This approach is recommended if you have enough information to create a user, but it is not complete and you plan to update the user manually.  Using Hybrid SSO, after you manually update the user’s account, the SSO integration would not overwrite your changes upon subsequent logins. 

Claim Details 

* Multiple claims can be sent to assign more than one value for this claim to the user.  

Claims by Account Management Type 

I-9 Manager Claims 

* Used as the identifier to determine if the user exists already or not. 

** For the user you create to have access to any Employee or Form I-9 records, you must specify access permissions for the user: 

• If you send “All Client Access” then you would not send (and we would ignore) any Employer, Security Group, or Worksite values, since they overlap. 
• If you send one or more Employer values, we would ignore any Security Group or Worksite values within that Employer, since they overlap. 
• You may send a combination of Security Group and Worksite values, though we will ignore any worksite values that exist within the sent Security Groups, since they overlap. 

SP Initiated SSO

The following explains the different use cases and how the system will handle errors:  

1. User clicks on the link for Scarlet which contains ClientID  in the url: https://i9complete.com/sso/C{clientId} 
2. Validate ClientID and Domain hint 
   • If ClientId does not exists, user is directed to error page with message: SSO01: ClientId is invalid.  
   • DomainHint is retrieved from DB based on clientId, which is used by B2C to redirect the user to their IDP login page. 
   • If valid proceed to step 3.  
3. User is directed to IDP for authorization. 
4. Enter username and password.  
   • After authorization user is created in azure b2c if it is not already there. Then, it is directed to STS application. 
5. Check for claim accountmanagementtype, if not present set it to Authorization Only. 
6. If accountmanagementtype is Authorization Only, get user information using username, email, or external id claim. 
   • If username Claim is given, get user information using it else get it using email or externalId. 
     • If none of the able is provided, user is directed to error page with message: SSO07: You must provide either a Username, Employee ID, or Email Address claim. 
     • If either is provided but user does not exist, then user is directed to error page with following error: SSO08: User not found. 
   • If user exists 
     • But it is not enabled, then direct to error page with message: SSO03: This account is currently inactive. 
     • If user does not have client associated or if client is inactive, user is directed to error page with message: SSO04: Client is inactive 
     • If user does not have SSO login enabled, then user is directed to error page with message: SSO05: SSO Login Access is denied. 
     • If user’s client does not match with given client Id, then user is directed to error page with following message: SSO14: User does not belong to the provided client. 
     • Else, user is authenticated and directed to scarlet application. 
7. If accountmanagementtype is Dynamic User Management 
   • Get the user information using username.  
   • If user does not exist, then 
     • Get the name claim, if not provided user is directed to error page with message: SSO09: You must provide a Username claim. 
     • Get the givenname claim, if not provided user is directed to error page with message: SSO10: You must provide a value for the GivenName claim. 
     • Get the surname claim, if not provided user is directed to error page with message: SSO11: You must provide a value for the Surname claim. 
     • Get the email claim, if not provided user is directed to error page with message: SSO12: You must provide a value for the Email claim. 
     • If none of the following claims is provided worksiteExternalId, securityGroupExternalId, employerExternalId, worksiteId,securityGroupId, employerId, allClientAccess, then user is directed to error page with message: SSO13: You must provide the user's level of access with one or more Worksite Ids, Security Group Ids, Employer Ids, or All Worksite Access claim. 
     • Else, save the user, then redirect the user to scarlet application.
   • If user exists  
     • But it is not enabled, then direct to error page with message: SSO03: This account is currently inactive. 
     • If user does not have client associated or if client is inactive, user is directed to error page with message: SSO04: Client is inactive 
     • If user does not have SSO login enabled, then user is directed to error page with message: SSO05: SSO Login Access is denied. 
     • If user’s client does not match with given client Id, then user is directed to error page with following message: SSO14: User does not belong to the provided client. 
     • Else, user account is updated and authenticated then directed to scarlet application. 
8. If accountmanagementtype is Hybrid 
   • Get the user information using username. 
   • If user exist, then 
     • If user is not enabled, then direct to error page with message: SSO03: This account is currently inactive. 
     • If user does not have client associated or if client is inactive, user is directed to error page with message: SSO04: Client is inactive 
     • If user does not have SSO login enabled, then user is directed to error page with message: SSO05: SSO Login Access is denied. 
     • If user’s client does not match with given client Id, then user is directed to error page with following message: SSO14: User does not belong to the provided client. 
     • Else, user is authenticated and directed to scarlet application. 
   • If user does not exist, then  
     • Get the name claim, if not provided user is directed to error page with message: SSO09: You must provide a Username claim. 
     • Get the givenname claim, if not provided user is directed to error page with message: SSO10: You must provide a value for the GivenName claim. 
     • Get the surname claim, if not provided user is directed to error page with message: SSO11: You must provide a value for the Surname claim. 
     • Get the email claim, if not provided user is directed to error page with message: SSO12: You must provide a value for the Email claim. 
     • If none of the following claims is provided worksiteExternalId, securityGroupExternalId, employerExternalId, worksiteId,securityGroupId, employerId, allClientAccess, then user is directed to error page with message: SSO13: You must provide the user's level of access with one or more Worksite Ids, Security Group Ids, Employer Ids, or All Worksite Access claim. 
     • Else, save the user, then redirect the user to scarlet application.

IDP Initiated SSO

The following explains the different use cases and how the system will handle errors:  

1. User navigates to their IDP and authenticates. The user has to be authenticated to access application within IDP   
2. Enter username and password and access to IDP. 
3. User click on application created in their IDP. The application User clicks on the link for Scarlet which contains ClientID and domain hint in the url: https://i9complete.com/sso/C{clientId} 
4. Validate ClientID and Domain hint 
   • If ClientId does not exists, user is directed to error page with message: SSO01: ClientId is invalid.  
   • DomainHint is retrieved from DB based on clientId, which is used by B2C to redirect the user to their IDP login page. 
   • If valid proceed to step 3.  
5. User is directed back to IDP for authorization. Since the user has been already authenticated when accessing to IDP it bypasses the authentication. 
6. User is then created in azure b2c if it is not already there. Then, it is directed to STS application. 
7. Check for claim accountmanagementtype, if not present set it to Authorization Only. 
8. If accountmanagementtype is Authorization Only, get user information using username, email, or external id claim. 
   • If username Claim is given, get user information using it else get it using email or externalId. 
     • If none of the able is provided, user is directed to error page with message: SSO07: You must provide either a Username, Employee ID, or Email Address claim. 
     • If either is provided but user does not exist, then user is directed to error page with following error: SSO08: User not found. 
   • If user exists 
     • But it is not enabled, then direct to error page with message: SSO03: This account is currently inactive. 
     • If user does not have client associated or if client is inactive, user is directed to error page with message: SSO04: Client is inactive 
     • If user does not have SSO login enabled, then user is directed to error page with message: SSO05: SSO Login Access is denied. 
     • If user’s client does not match with given client Id, then user is directed to error page with following message: SSO14: User does not belong to the provided client. 
     • Else, user is authenticated and directed to scarlet application. 
9. If accountmanagementtype is Dynamic User Management 
   • Get the user information using username.  
   • If user does not exist, then 
     • Get the name claim, if not provided user is directed to error page with message: SSO09: You must provide a Username claim. 
     • Get the givenname claim, if not provided user is directed to error page with message: SSO10: You must provide a value for the GivenName claim. 
     • Get the surname claim, if not provided user is directed to error page with message: SSO11: You must provide a value for the Surname claim. 
     • Get the email claim, if not provided user is directed to error page with message: SSO12: You must provide a value for the Email claim. 
     • If none of the following claims is provided worksiteExternalId, securityGroupExternalId, employerExternalId, worksiteId,securityGroupId, employerId, allClientAccess, then user is directed to error page with message: SSO13: You must provide the user's level of access with one or more Worksite Ids, Security Group Ids, Employer Ids, or All Worksite Access claim. 
     • Else, save the user, then redirect the user to scarlet application 
   • If user exists  
     • But it is not enabled, then direct to error page with message: SSO03: This account is currently inactive. 
     • If user does not have client associated or if client is inactive, user is directed to error page with message: SSO04: Client is inactive 
     • If user does not have SSO login enabled, then user is directed to error page with message: SSO05: SSO Login Access is denied. 
     • If user’s client does not match with given client Id, then user is directed to error page with following message: SSO14: User does not belong to the provided client. 
     • Else, user account is updated and authenticated then directed to scarlet application. 
10. If accountmanagementtype is Hybrid 
    • Get the user information using username. 
    • If user exist, then 
      • If user is not enabled, then direct to error page with message: SSO03: This account is currently inactive. 
      • If user does not have client associated or if client is inactive, user is directed to error page with message: SSO04: Client is inactive 
      • If user does not have SSO login enabled, then user is directed to error page with message: SSO05: SSO Login Access is denied. 
      • If user’s client does not match with given client Id, then user is directed to error page with following message: SSO14: User does not belong to the provided client. 
      • Else, user is authenticated and directed to scarlet application. 
    • If user does not exist, then  
      • Get the name claim, if not provided user is directed to error page with message: SSO09: You must provide a Username claim. 
      • Get the givenname claim, if not provided user is directed to error page with message: SSO10: You must provide a value for the GivenName claim. 
      • Get the surname claim, if not provided user is directed to error page with message: SSO11: You must provide a value for the Surname claim. 
      • Get the email claim, if not provided user is directed to error page with message: SSO12: You must provide a value for the Email claim. 
      • If none of the following claims is provided worksiteExternalId, securityGroupExternalId, employerExternalId, worksiteId,securityGroupId, employerId, allClientAccess, then user is directed to error page with message: SSO13: You must provide the user's level of access with one or more Worksite Ids, Security Group Ids, Employer Ids, or All Worksite Access claim. 
      • Else, save the user, then redirect the user to scarlet application.