CAS Strategy for Überauth.

Redirects the user to a CAS login page and verifies the Service Ticket the CAS server returns after a successful login.

The login flow looks like this:

1. User is redirected to the CAS server's login page by Ueberauth.Strategy.CAS.handle_request!/1

2. User signs in to the CAS server.

3. CAS server redirects back to the Elixir application, sending a Service Ticket in the URL parameters.

4. The Service Ticket is validated by this Überauth CAS strategy, fetching the user's information at the same time.

5. The user can proceed to use the Elixir application.

Protocol compliance

This strategy only supports a subset of the CAS protocol (version 2.0 and 3.0). Notable, there is no support for proxy-related stuff.

More specifically, it supports following CAS URIs:

• /login

  The strategy supports calling /login to enable the user to login. This is known as the credential requestor mode in the CAS specification.

  The strategy only supports the service parameter, and currently does not provide support for renew, gateway or method.

• /serviceValidate

  After a successful login, the strategy validates the ticket and retrieves information about the user, as described in the specification.

  The strategy only supports the required params, service and ticket. There is no support for other params.

  The validation path can be overridden via configuration to comply with CAS 3.0 and use /p3/serviceValidate.

Errors

If the login fails, the strategy will fail with error key missing_ticket.

If the ticket validation fails, the error key depends:

• If the response is no valid XML, the error key is malformed_xml.
• If there is proper error code in the CAS serviceResponse, the error code will be used as error key, while the description will be used as error message.
• In other cases, the error key will be unknown_error.

User data

In the ticket validation step (step 4), user information is retrieved. See Ueberauth.Strategy.CAS.User for documentation on accessing CAS attributes. Some attributes are mapped to Überauth info fields, as described below.

Raw XML payload

To retrieve the initial XML payload, you must set the option return_xml_payload: true.

To retrieve it, you can call:

iex> Cas.extra(conn)
%Extra{
  raw_info: %{
    user: %CAS.User{
      name: "Marcel de Graaf",
      attributes: %{
        "email" => "mail@marceldegraaf.net",
        "roles" => "developer",
        "first_name" => "Marcel"
      }
    },
    xml_payload: ~s(
      <cas:serviceResponse xmlns:cas="http://www.yale.edu/tp/cas">
      <cas:authenticationSuccess>
        <cas:user>mail@marceldegraaf.net</cas:user>
        <cas:attributes>
          <cas:authenticationDate>2016-06-29T21:53:41Z</cas:authenticationDate>
          <cas:longTermAuthenticationRequestTokenUsed>false</cas:longTermAuthenticationRequestTokenUsed>
          <cas:isFromNewLogin>true</cas:isFromNewLogin>
          <cas:firstName>Marcel</cas:firstName>
          <cas:lastName>de Graaf</cas:lastName>
          <cas:roles>developer</cas:roles>
        </cas:attributes>
      </cas:authenticationSuccess>
    </cas:serviceResponse>
    )
  }
}copy

Default mapping

By default, attributes are the same as the Überauth field. For example, the field :last_name will be set from an attribute cas:lastName.

This can be disabled by explicitly setting the :sanitize_attribute_names option to false.

Configuring Überauth mapping

The mapping can be specified in the configuration:

config :ueberauth, Ueberauth,
   providers: [cas: {Ueberauth.Strategy.CAS, [
     base_url: "http://cas.example.com",
     validation_path: "/serviceValidate",
     callback_url: "http://your-app.example.com/auth/cas/callback",
     attributes: %{
        last_name: "surname"
     },
   ]}]copy

Multivalued attributes

By default, only the first value is kept in case of multivalued attributes. This behaviour can be managed with the mutivalued_attributes option, which can be set to :first, :last or :list.