---
title: "SSO (single-sign-on)"
canonical: "https://red-ant-documentation.refined.site/space/RET/362250241/SSO%20(single-sign-on)"
format: markdown
---
## Overview

Out-of-the-box RetailOS has its own authentication method, however, it also supports single-sign-on (SSO) via the SAML protocol.

## Getting started with SSO 

#### Summary 

SSO (Single Sign On) is a development system which allows a user to log into multiple systems using one central set of login credentials. This makes life much easier for the user, and it also makes it much easier for businesses to manage user access and security. RetailOS integrates with SSO systems using SAML 2.0 protocol to provide simple access for all users. The integration information is established via two metadata files – set up independently for each environment. RetailOS acts as the ‘Service Provider’ (SP), the retailer’s SSO service acts as the ‘Identity Provider’ (IdP). Within this guide, we run through the key steps and requirements to complete the integration. 

#### Step 1 - Service Provider Setup 

Red Ant will provide a set of ”Service Provider” metadata files - these will be provided for each environment (typically QA, UAT and Live). The metadata files should then be added to the SSO service as new service provider. This is typically completed via an admin dashboard, however, the exact implementation can vary based on the service. Please note, a single SSO service can be used to sign-in on all RetailOS environments, each one would just need to be set up as a separate service provider. 

#### Step 2 - IP Metadata 

Once the service providers have been set up, the SSO service will provide a mechanism to download an Identity Provider metadata file (this will be an XML file). Once you have downloaded this, please forward this to your Red Ant team. We’ll then use this file to tell our system where to go and how to interact with your SSO service when login is initiated. 

#### Step 3 Ensuring the right users have access 

Typically, when integrating with an SSO, not all the users within the SSO’s remit should have access to RetailOS. In order to manage these permissions, you can assign sets of users or user groups to be allowed access to the RetailOS Service Provider(s) you have set up in your SSO service. Access to the RetailOS Service Provider will mean these users will be authenticated successfully when logging into RetailOS. 

#### Step 4 - Database Syncing 

In the instance that you already have users set up on the RetailOS database, please advise your Red Ant team whether any/all of these users will need to be migrated to SSO login. In the instance that a username already exists in RetailOS and has a matching username in SSO, this user will need to be migrated. 

#### Configuration options

RetailOS SSO supports the following configuration options. 

- JIT (Just In Time) Provisioning - Allows automatic user creation on successful login. Requires a user role, either via a default role or by role mapping. If JIT is not enabled, users will need to be created in RetailOS **before** their first log in via SSO
- Managed Stores - manage a user’s stores through SSO, requires a claim to be mapped to a list of store Ids.
- Managed Roles - manage a user’s role through SSO, requires a claim to be mapped to a valid RetailOS role.
- Managed Departments - manage a user’s departments through SSO,  requires a claim to be mapped to a list of department Ids.
- Strict Store Mapping - Only when managing stores through SSO. If enabled, the store claim must strictly map to at least one valid RetailOS store.
- Strict Role Mapping - The same as above for user role.
- Strict Department Mapping -  The same as above for departments.
- Default Stores - An optional list of default stores to use when provisioning new users (JIT provisioning)
- Default Role - An optional default role to use when provisioning new users (JIT provisioning)
- Default Departments - An optional list of default departments to use when provisioning new users (JIT provisioning)
- Attribute mapping - define how assertion claims are mapped to RetailOS user data.

#### Important information 

Once Red Ant have been provided the IdP metadata file and have configured the server, an option for SSO Login will appear in app. An option to manually sign in will remain to allow your Red Ant team to continue to access the application for development and support purposes.

#### Dependencies

| **Dependency** | **Responsible** |
| --- | --- |
| - [ ] Provide Serivce Provider metadata files (for each environment) to client | [RED ANT] |
| - [ ] Service Provider metadata files to be added SSO service as new service provider | [CLIENT] |
| - [ ] Provision of Identifty Provider metadata | [CLIENT] |
| - [ ] Assign users or user groups to be allowed access to the RetailOS Service Provider(s) you have set up in your SSO service | [CLIENT] |
| - [ ] Provision of SSO login credentials | [CLIENT] |
| - [ ] Server configuration | [RED ANT] |
| - [ ] Enable ‘SSO Login’ option | [RED ANT] |