Configure SAML SSO
Steps required for enabling SAML single sign on for users logging in to PlaceOS web apps
By default, PlaceOS uses local authentication. An admin account is generated upon initial deployment. The administrator can manually create user accounts in Backoffice (on the Users tab). We recommend switching to federated authentication.
Prerequisites
Confirm the final UAT and PROD URLs of the web apps
Ensure that the DNS entries for these URLs are active and forwarding to the server(s)
Ensure that the SSL certificates for the above domains are signed and recognized as secure
Step 1: Adding Authentication
Login as an admin to Backoffice
On the Domains tab, select the Domain that represents the URL where you wish to enable SAML
In the Authentication section click Add new
This will open up the SAML form. Here is a description of each field:
Name
: generic field for identifying the SSOIssuer (Identifier / Entity ID)
: this is what the SSO will use to identify this SSO integrationCan be anything, typically use the DNS entry i.e.
staffapp.company.com
Azure will be in the format:
spn:**client-id**
- "Application (client) ID" can be found on the Overview page of your App RegistrationOKTA will need the Issuer to be configured in the OKTA Application to match the value set here
IDP target URL
: This is the URL where SSO will occur - the login pageYou can often guess it, but you can set it to any valid URL and change it later
Request this URL when sending the metadata URL
Azure AD URLs are often in the format:
https://login.microsoftonline.com/**tenant-ID**/saml2
OKTA URLs are often in the format:
https://**okta.domain.com**/app/**app-name**/**app-id-number**/sso/saml
AD FS URLs are often in the format:
https://adfs.myorganistaion.com/adfs/ls
Auth0 URLs are often in the format:
https://myorganisation.auth0.com/samlp/
Name Identifier Format
: the format of the response dataSet to
urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified
Request Attributes
: these are the Active Directory fields requested to be sent to usTypically leave this blank on first save, and it will fill in the default value
Clients sometimes request you change these to match their system
Example:
Assertion URL (Reply URL / Callback URL)
: the PlaceOS URL that SSO sends data back to - to log someone inFirst set this to the base domain of the application. After saving this configuration for the first time, it will generate an ID (
adfs_strat-XXXXXX
)See the image below and use the generated unique ID to build the Assertion URL
Certificate Fingerprint / Full Certificate
: used for verifying a signed login requestNot required until after SSO configuration on the client-side
UUID Attribute
: allows you to override the default unique ID returned by SSO to one of the requested attributesAttribute Statements
: This maps requested attributes to database fieldsTypically leave this blank on first save, and it will fill in the default value
Example:
Once you click save, it will generate an authentication ID. You can find it in the /saml_auths
response on the Authentication tab.
URL configuration
Set the following fields to the corresponding URLs, replacing
adfs-XXXXX
with the generated ID:Assertion URL (Reply URL / Callback URL):
https://staffapp.placeos/auth/adfs/callback?id=adfs-XXXXX
Metadata URL:
https://staffapp.placeos/auth/adfs/metadata?id=adfs-XXXXX
Login URL:
https://staffapp.placeos/auth/adfs?id=adfs-XXXXX
Edit the authentication and update the Assertion URL with the one you have created above
Email the client with:
The Metadata URL so they can configure their systems
A request for their IDP target URL
A request for their logout URL if they have one (otherwise can redirect to company home page etc)
PlaceOS supports signed SSO but not encrypted. SSL transport means the SSO response payload is already encrypted
Once the client has configured their side, they’ll often ask you to change some information. This could be the Issuer, or some request attributes.
Step 2: Register a new service in your authentication provider
You will need to configure your SAML Identity provider dashboard. From the above steps you will need:
The Issuer (also known as the Identifier)
The Assertion URL (also known as the Callback URL)
The Login URL which is the homepage of the app
The Metadata URL (optional)
This XML file contains the above information and can be fed into to some configuration dashboards (like AD FS).
This process will vary by provider, see the below guides for common options:
Step 3: Configure default redirects for the PlaceOS Domain
Once you have tested the Login URL above you can update the default login page for the domain.
Click the edit icon for the Domain (above the authentication tab)
Set the login URL to
/auth/login?provider=adfs&id=[ADFS-ID-HERE]&continue={{url}}
, replacing the[ADFS-ID-HERE]
and leaving the{{url}}
as isSet the logout URL to
/auth/logout?continue=https://sso.org.com/logout
if they haven’t provided you a logout
Debugging
The first step in this process should be to get the raw request. Often you can see if a request attribute is not lining up to an attribute statement by inspecting the XML.
You can paste the resulting data into this SAML Decoder
Then paste the XML into Pretty Print (so it’s readable)
There are two methods of getting SSO data, described below:
If you have an account you can use to test
If the client is logging in and you have access to logs
Self Check
Open the Chrome or Firefox inspection tool
Go to the network tab
Select: preserve log
Go through the login flow
The request coming back to the assertion URL is the one you want to inspect.
Assertion URL: /auth/adfs/callback?id=[ADFS-ID-HERE]
Copy and paste the SAML response into the SAML decoder.
Docker logs
Look for the text "Callback phase initiated" and the SAML response data is nearby.
Last updated