Graphene SSO CAS Configuration - EscherLabs/Graphene GitHub Wiki
This document details how to configure Graphene for use with CAS Single-Sign-On, as well as how to map user parameters to Graphene during the sign-on process.
Video Tutorial
CAS Hostname:*
This is the hostname of your CAS Server.
Example: cas.example.com
CAS Real Hosts:*
This is / these are the hostname(s) of your CAS Server(s) and is used when SAML is active to help protect against DOS attacks. If using load balanced hosts, separate each with a comma.
Example: cas.example.com
CAS URI:*
This is the URI for CAS on the CAS Server.
Example: /cas
CAS Port:*
This is the port on which CAS listens (http/port 80 vs. https/port 443)
Example: HTTPS (443)
CAS Login URL:
This is the full CAS Login URL.
If this is left blank, the login url is assumed to be:
http(s)://[CAS Hostname][CAS URL]/login
Example: https://cas.example.com/cas/login
CAS Logout URL:
This is the full CAS Logout URL.
If this is left blank, the logout url is assumed to be:
http(s)://[CAS Hostname][CAS URL]/logout
Example: https://cas.example.com/cas/logout
CAS Enable SAML:
This will either enable CAS SAML logons (Enabled) or fall back on default CAS logins (Disabled). With this option enabled, it is possible to expose multiple user attributes to Graphene during the authentication process. If this is disabled, only the username field is returned from CAS.
Note: If this is disabled, the authenticated user's username (as it is returned by CAS) is exposed via a "username" variable. If used in conjunction with the "External User Lookup", the "username" field will be sent as a GET/POST variable to that endpoint. Alternatively, or in addition, it is possible to map the "username" field directly to a Graphene user's unique_id by using the standard {{username}} mustache syntax in the "unique_id" field below.
Example: Enabled
External User Lookup:
If enabled, this allows the login process to supplement the user attributes available to Graphene by performing an external attribute lookup. During this process, all attributes received from the login process are sent to the User Lookup URL (below), and the JSON Object returned is merged into the available user attributes array.
Note: If the external user lookup fails (server is offline / server returns something other than a "200" response code / server returns invalid JSON data), the external lookup will be ignored and a login attempt will continue with only the currently available data. As a result, it is not recommended to rely on these attributes for mission critical fields (example: Graphene unique_id) unless 100% uptime of the external user lookup server can be assured.
Example: Enabled
External User Lookup URL:
This is the URL used to look up additional user attributes.
Example: https://example.com/userlookup
External User Lookup Verb:
This is the HTTP Verb (GET/POST) which is used to look up additional user attributes.
Example: GET
Email:
This is a "mustache" representation of the email address field as it will be mapped to a user object within Graphene. To set the "email" field, you may use any available mustache syntax against any of the user attributes as made available from the SSO Login, or as part of the external user lookup process.
Note: Email addresses within Graphene must be unique. If a user attempts to log into Graphene with a non-unique username, a "401" error will be thrown.
Example 1: {{email_address}}
Example 1 assumes that the email_address field is exposed via CAS (with SAML enabled), or via an additional user attribute lookup using CAS (without SAML).
Example 2: {{username}}@example.com
Example 2 assumes that the username field has been returned from the CAS SSO process (likely SAML disabled), and that the username, when concatenated to "@example.com" makes up the email address.
First Name:
This is a "mustache" representation of the user's "first name" as it will be mapped to a user object within Graphene. To set the "first name" field, you may use any available mustache syntax against any of the user attributes as made available from the SSO Login, or as part of the external user lookup process.
Example 1: {{first_name}}
Example 2: {{#first_name}}{{first_name}}{{/first_name}}{{^first_name}}{{username}}{{/first_name}}
Example 2 uses standard mustache syntax to determine if the "first_name" field exists and is non-empty. If it does, that field is used. If it does not, the "username" field is used instead. This can be useful to provide a fallback if certain attributes are missing for certain users, or if the external user lookup may be down during an initial login attempt.
Last Name:
This is a "mustache" representation of the user's "last name" as it will be mapped to a user object within Graphene. To set the "last name" field, you may use any available mustache syntax against any of the user attributes as made available from the SSO Login, or as part of the external user lookup process.
Example: {{last_name}}
Unique ID:
This is the unique identifier used within Graphene to differentiate between individual users. This field must be unique, and must map to a single user.
Note that while it is possible for Graphene to reference a unique_id field which is returned by an "external user lookup" (not returned by the initial CAS Login), this is not recommended unless the uptime of the "external user lookup" server is close to 100%.
Example 1: {{username}}
Example 1 assumes that the username field is unique. (This is typically used with CAS SSO, when SAML has been disabled)
Example 2: {{pidm}}
Example 2 assumes that the pidm field is unique, and is exposed by CAS SSO (with SAML enabled).
CAS Data Map
These additional (optional) mappings allow for additional fields to attributed to a user, outside of the default fields built into Graphene.
Examples:
| Name | Value |
|---|---|
| full_name | {{first_name}} {{last_name}} |
| pidm | {{SPRIDEN_PIDM} |
| favorite_color | {{favorite_color}} |