Versions Compared
Key
- This line was added.
- This line was removed.
- Formatting was changed.
If you 're an administrator with the have the Administration > Configuration permission, you can enable the single sign-on to Phocas.
Learn about single sign-on
The ‘single sign-on’ (SSO) feature for your Phocas site.
The SSO feature uses a trusted third-party identity provider (IDPIdP) to allow users to manually sign in to Phocas with the same credentials they use for other applications. Single sign-on SSO uses a standard web protocol known as SAML ( Security Assertion Markup Language (SAML), which works by securely passing passes a user’s identity from one place (IdP) to another (Phocas) via encrypted, digitally signed XML certificates, in other words, from your IDP to Phocas, XML certificates.
When you enable single sign-on, users will see an additional button (Sign-in via...) SSO for your Phocas site:
Users will see a Sign in… button on the Phocas sign
in screen,
allowing them
to sign in via the
IdP.
- Image Added
When
users sign in using this method:
If
they are already authenticated with your
IdP, they are taken straight into Phocas.
If they
are not yet authenticated, they are taken to a second sign
in
screen, where they enter their credentials for the
IdP.
When the user is finished using users finish their session in Phocas, they still need to manually sign out of Phocas in the usual way, even if they have signed out of other applications that use the IDPIdP. Without signing out, the duration of a session will depend on your provider IdP and other factors, such as how often the users clear cookies.
Enable single sign-on
Click In the Phocas menu button > , click Administration > Configuration, then scroll down to the SAML sectionclick the Single sign-on (SSO) tab.
Select the Enable Allow SSO via SAML checkbox. The SAML configuration settings display.Configure the SAML:
Enter the Identity Provider (IDP) information. See note below for more IdP) information.
Copy the Service Provider (SP) and paste it into your IDP application. See note below for more information.
Click Save.
Expand | ||
---|---|---|
| ||
As shown in the image below, there there are some details you will need to get from the IDP IdP you are using. It can be useful to have the Configuration screen and the relevant settings page from your IDP IdP open side by side. Depending on your provider, this information might be called something different to from what it is called in Phocas. The X509 Certificate is a commonly used standard in internet protocols and, although it is not compulsory, it is strongly recommend recommended that you copy these details from your IDP IdP and enter them into Phocas. If you make an error when pasting and when doing this, when you try to save your configuration changes, the certificate text will turn red and show an error message. Check you have copied the entire text and have not accidentally added spaces or deleted anything. Image RemovedImage Added |
Copy the Service Provider (SP) and paste it into your IdP application.
Expand | ||
---|---|---|
| ||
title | SpecificWhen you enable SAML, Phocas will automatically populate the details in the Service Provider (SP) section. The service provider is the system (Phocas) that wants to use SAML to authenticate its users. Click the Copy button to copy this information and paste it into to the relevant fields in your IDP IdP application. Image RemovedImage AddedIf you have an on-premise installation of Phocas, you are also asked for an Application URL. You You’ll find this in the top General tab > Defaults section of the Configuration screen. Image Removed | |
Expand | ||
. |
Select the Enhanced SAML Security checkbox (recommended).
Expand | ||
---|---|---|
| ||
The Enhanced SAML Security setting is recommended. It changes the look of the Phocas sign in screen to promote the SAML authentication method.
|
(Optional) Select the Update user account with details from IdP on user sign-on checkbox.
Expand | ||
---|---|---|
| ||
If you select the Update user account… checkbox, you activate the user details sync process. Each time a user signs in to Phocas, the details in their Phocas account are automatically synced (updated) with their IdP details. The sync works in one direction only; details are passed from the IdP to Phocas, so the IdP is the single source of truth. Currently, the following details are passed to Phocas from the IdP: Display Name, Given Name, Surname and Contact Email, as highlighted in the image below. Other special attributes (such as telephone, mobile phone, groups, territory and team) might also be passed through, depending on your IdP setup. Here is an example of where IdP (Azure AD) attributes are mapped to the special Phocas attributes. Image AddedUsers can still edit their details in Phocas (via user account settings) but the next time they sign in to Phocas, those details will be overwritten with whatever is in the IdP. If users need to update their details, they should get their IdP administrator to update them, then they will flow through to Phocas. |
(Optional) Select the Automatically create user account if none exists checkbox, then select a template, if required.
Expand | ||
---|---|---|
| ||
The User account creation feature applies to IdP-authorized users who do NOT currently have a Phocas account. If you enable this feature, when such a user tries to sign in to Phocas using SAML, a Phocas account will be automatically created for them. Templates are available if you have created them for your site. If you select a template, the user’s Phocas account is based on that template. If you do not select a template, the user gets the default Phocas account, which has a Viewer license and Viewer permissions (limited data access). You can update the user account later. If you create multiple templates in Phocas, you can set up your IdP to determine which of those templates is used when each new user account is automatically created in Phocas. For example, if an IdP authorized user is part of an administrator group, you can select the corresponding template for that group (one with administration permissions). Phocas will use that template instead of the default template when creating an account for that user. Any details from the IdP passed along on sign in will overwrite the equivalent details of the template. For example, if a template has its Groups set to Group 1 but the IdP passes Group 2, the resulting newly created user will be set to Group 2. Here is an example of where IdP (Azure AD) is set up to use templates. The phocasUserTemplate is the one that drives the default template for the user. Note how the group membership is used to select which template should be used. Image Added |
Click Save.
Expand | ||
---|---|---|
| ||
In an IDPIdP-initiated single sign-on flow, the IDP IdP might supply a path to a specific resource (such as an embedded favorite) in the RelayState parameter of the request. When the sign-on successfully occurs, the application automatically directs to the URL specified in the RelayState parameter. For example, the RelayState below specifies the path '/favourite/Embed/3140' - which identifies a particular favorite in Phocas. Image Removed When the user signs in successfully via a SAML request, they are automatically taken to the favorite, as shown below. Image RemovedImage Added |