Versions Compared

Old Version 35

changes.mady.by.user Denise McGettigan

Saved on

compared with

New Version Current

changes.mady.by.user Denise McGettigan

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Panel
panelIconId2699
panelIcon:gear:
panelIconText⚙️
bgColor#EAE6FF

Administration permission required: Configuration

The ‘single sign-on’ If you have the Administration > Configuration permission, you can enable 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.

Learn about how single sign-on impacts users

, 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,

giving

  • allowing them

the option

  • to sign in via the

IDP

  • IdP.

Image Removed
  • Image Added

  • When

the user clicks this button

  • users sign in using this method:

    • If

    the user is

    • they are already authenticated with your

    IDP

    • IdP, they are taken straight into Phocas.

    • If they

    're

    • are not yet authenticated, they are taken to a second sign

    -

    • in

    window

    • screen, where they enter their credentials for the

    provider

    • 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

  1. Click In the Phocas menu button > , click Administration > Configuration, then scroll down to the SAML sectionclick the Single sign-on (SSO) tab.

  2. Select the Enable Allow SSO via SAML checkbox. The SAML configuration settings display.

  3. Enter the Identity Provider (IDPIdP) information. See note below for more information.

  4. Copy the Service Provider (SP) and paste it into your IDP application. See note below for more information.

  5. Click Save.

Expand
titleInformation about the IDP you enter in Phocasinformation you need...

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 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-20240718-035931.pngImage Added

  1. Copy the Service Provider (SP) and paste it into your IdP application.

Expand
titleInformation about Phocas you provide to your IDPSP information...

When 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 Added

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

  1. Select the Enhanced SAML Security checkbox (recommended).

Image Removed ExpandtitleSpecific

Expand
titleEnhanced SAML security...

The Enhanced SAML Security setting is recommended. It changes the look of the Phocas sign in screen to promote the SAML authentication method.

  • SAML users will only be able to sign in to Phocas using SAML.

  • SAML user passwords will not be resettable in Phocas.

  • Non-SAML users can still sign in to Phocas via the link below the Sign in button.

image-20240718-040446.pngImage Added

  1. (Optional) Select the Update user account with details from IdP on user sign-on checkbox.

Expand
titleUpdate user accounts...

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 Added

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

  1. (Optional) Select the Automatically create user account if none exists checkbox, then select a template, if required.

Expand
titleUser account creation and templates...

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

  1. Click Save.

Expand
titleAdditional information - when an IdP has a specific URL to a favorite or other resource

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 Removed

Image Added

Image Added

Related page