[Index]

Model: data/SsoIdentityProvider

Single Sign On (SSO) Authentication

The VOSS-4-UC system supports Single Sign On so that authentication credentials configured at an Identity Provider (IDP) can be related to a VOSS-4-UC user and can then be used to log in on the system.

The VOSS-4-UC system uses the SAML 2.0 standard for authentication and authorization data exchange.

The scenario supported by VOSS-4-UC is as follows:

1. A user attempts to access VOSS-4-UC by clicking on a bookmark in a customer's portal.
   1. The bookmark contains an URL to the IDP, with an URL parameter that indicates that the IDP must redirect to the chosen Service Provider (VOSS-4-UC).
2. The HTTP request is sent to the IDP.
   1. If the user already has a session with the IDP, the request is forwarded to VOSS-4-UC without prompting for a password.
   2. If the user does not have a session with the IDP, the user is prompted to login and redirected to VOSS-4-UC upon successful authentication.
3. Upon redirection to VOSS-4-UC, the HTTP request from the IDP will contain an assertion that contains attribute information about the user to be authorized by VOSS-4-UC.
4. VOSS-4-UC validates the assertion and either:
   1. Proceeds to grant the user access, or
   2. Declines the user access

The overall procedure to enable SSO is the following (the VOSS-4-UC models are indicated where required):

• If the Use Custom Certificate for Signing check box is checked, add public and private keys to communicate with identity managers (File), or if the Use Custom Certificate for Signing check box is unchecked, choose a System Generated Certificate from the drop-down list (File)
• Configure VOSS-4-UC as a SSO service provider (SSO Settings)
• Configure the Identity Provider to connect to VOSS-4-UC
• Add the Identity Provider in VOSS-4-UC (SSO Identity Provider)
• Map a VOSS-4-UC user to an Identity Provider user (SSO User)

Add SSO Identity Provider

1. Download the meta data of the Identity Provider or obtain the certificate to verify the authenticity of the meta data downloaded from the Identity Provider. Refer to the documentation provided by the Identity Provider.
2. Choose the hierarchy for the Identity Provider.
3. Add an instance to the SsoIdentityProvider model.
4. On the Base tab, enter the Entity Id of the Identity Provider or Identity Broker. This is a URL.
5. Enter the Login URI. It only contains alphanumeric characters and forward slashes ("/") (it should match the following regular expression ^\w+(/\w+)*$). For example, given a login URI of provider1/customer1, end users wishing to authenticate against this IDP will login via the following URL: http://hostname/sso/provider1/customer1/login/.
6. On the Metadata tab, either specify a local metadata file or a remote metadata URL. If the metadata is a Remote Metadata URL, specify the URL. Public key files must be pre-loaded as part of the system configuration by using the Files menu option from Network Administration > SSO. Uploaded public key files are available from the Certificate drop down list.

Single Sign On (SSO) Troubleshooting

The following list provides troubleshooting solutions to common SSO problems.

• Browser error when moving a user in VOSS-4-UC to a sub-hierarchy.

  "Logout error". Your Identity Provider asks this system to do a global logout, but your federated session is lost. Even if your local session in this system has been closed, you may have probably open sessions in other systems. In order to prevent illicit use of your personal information, please close your browser window and/or remove your cookies from your browser.

• Error when attempting a logout while another browser window is still logged into the Identity Provider (IDP).

  The message that will be displayed is of the format:

{ message: "An internal system error occurred.",
  code: -1,
  http_code: 400,
  traceback: "Traceback (most recent call last):
  File "/opt/voss-deviceapi/eggs/Django-1
      .4.5-py2.7.egg/django/core/handlers/base.py", line 111,
 ...

• Access Rights Violated - Permission denied

  When logging in, you are re-directed to http://mydomain/sso/acs/ and the browser returns "Permission denied" while the heading in the browser tab shows "Access rights violated". The reason for this is that your browser is already logged into the IDP while you are trying an SSO login into VOSS-4-UC.

• Incorrect URL for ACS in the IDP leads to HTTP 301 and HTTP 405.

  If the assertion consumer service in the IDP's SP attributes is set incorrectly, the SAML trace is expected to provide a HTTP 301 and then a HTTP 405 error.

  The example trace illustrates that the URL in the IDP was set to

  http://mydomain/sso/acs

  and in VOSS-4-UC it was set to

  http://mydomain/sso/acs/

  The difference between the two items is shown below.

Request URL:http://mydomain/sso/acs
Request Method:POST
Status Code:301 MOVED PERMANENTLY

...

Response Headers view source
Connection:keep-alive
Content-Language:en-us
Content-Type:text/html; charset=utf-8
Date:Mon, 21 Oct 2013 14:35:00 GMT
Location:http://mydomain/sso/acs/
Server:nginx/1.2.1
Transfer-Encoding:chunked
Vary:Accept-Language

Request URL:http://mydomain/sso/acs/
Request Method:GET
Status Code:405 METHOD NOT ALLOWED
Request Headersview source

SSO logging

Basic logging of SSO requests takes place in the app.log file. View the logs via the platform Command Line Interface (CLI) using either of the commands (as for all other logs):

log view voss-deviceapi/app.log

or

log follow voss-deviceapi/app.log

An example of the kind of SSO logging text is:

Dec 20 10:02:45 localhost deviceapi.lib.auth.backends.sso_saml2 INFO Processing
 SAML2 SSO authentication request; Parsed SAMLResponse: {'authn_info':
 [('urn:oasis:names:tc:SAML:2.0: ac:classes:PasswordProtectedTransport', [])],
 'name_id': 'zUo+FcTbIKUW2UTwgG4hHVJUFoY+', 'not_on_or_after': 1387534388,
 'came_from': '/', 'ava': {'givenname': ['ssoadmin'], 'userid': ['ssoadmin']},
 'issuer': 'http://openamqa.visionoss.int:8080/openam'}

 Dec 20 10:02:45 localhost deviceapi.lib.auth.backends.sso_saml2 DEBUG uid not
  found in SAML AttributeStatement, falling back to name-id

Note that:

• the INFO entry is printed for all SAML2 assertions received from the IDP.
• the app.log file where this information is kept is used for other logging, so a search is needed for SSO log messages.

Standard Users and Login

When creating a system user that uses the standard authorization method, the password is stored in the internal system database. VOSS-4-UC uses the PBKDF2 algorithm with a SHA256 hash, a key stretching mechanism recommended by the National Institute of Standards Technology (NIST), Computer Security Resource Centre (CSRC).

When logging in as a standard VOSS-4-UC user, go to the URL:

http://{host name}/login

A Login page theme can be applied to the Login page during the log in process. Do this by adding the suffix '?theme=default' to the login request url. For example: http://{host name}/login/?theme=default, where 'default' is one of the themes available in VOSS-4-UC.

When logging in with VOSS-4-UC credentials, the username can be entered in either of the following formats:

{username}@hierarchy or {email address}

The hierarchy is in dot notation and corresponds with the hierarchy to which the user belongs, in other words the hierarchy level at which the user is created.

The hierarchy on the log in form is prefixed with sys.

For example: johndoe@sys.VS-OPS.VS-Corp.Chicago

See the following topics for more information relating to standard login:

• Credential Policies
• Password Expiry and Password Change Criteria

Stores details of an SSO Identity Provider.

Model Details: data/SsoIdentityProvider