Authentication and Authorization

In order to perform Authentication in Magpie, multiple Providers and methods are supported. By default, the Internal Provider named ziggurat is employed, which corresponds to the package used internally to manage all Magpie elements. Login procedure is covered in Authentication Requests section.

Supported External Providers are presented in the table below in section Authentication Providers, although more could be added later on.

Note

Terms Authentication Providers, External Providers and External Providers in this chapter must not be confused with providers employed in File: providers.cfg. In this chapter, providers refer to user-identity resolvers, in contrast to Service definitions from the configuration files.

Authentication Requests

The most convenient way to sign-in with Magpie is to employ the user interface provided on path {MAGPIE_URL}/ui/login. This page will present fields that allow both Internal Provider and External Provider login methods.

Alternatively, API requests can be employed to define your own interface, or to obtain request tokens needed to accomplish further requests interactions toward Magpie or obtain Authorization from the Proxy using Magpie to enforce policies.

Following are the supported request formats.

Request Method

Both GET and POST are supported. This is in order to allow resolution of credentials for some applications that do not correctly handle or purposely prohibit use of POST method. Also, GET helps quickly accomplishing a login from a web browser using the {MAGPIE_URL}/signin endpoint with query parameters (see Query Parameters).

Note

Whenever possible, prefer POST request with Body Content or the UI endpoint. See also warning in Query Parameters for details.

Query Parameters

This method employs the query string parameters in the URL to provide the credentials. The format is as follows.

GET {MAGPIE_URL}/signin?user_name=<usr>&password=<pwd>

The response will contain Authentication Headers detail needed for user identification.

Warning

Whenever possible, it is strongly recommended to instead use another one of the methods which offers better support for different Content-Type responses to interact with Magpie as an API.

Furthermore, using the POST method with content body and/or headers reduces risks of credential leaks that would be visible in plain text via query parameters using GET request. Most servers and applications log path and query parameters profusely, or even caches them, which can lead to easier identity theft or hacking of servers. The GET method remains available for backward compatibility and quick testing purposes only.

Body Content

Body content requests allow multiple variants, based on the specified Content-Type header. All variants employ a similar structure, but indicate the format of the body to be parsed. By default, application/json is employed if none was specified.

POST {MAGPIE_URL}/signin
Headers
    Content-Type: multipart/form-data; boundary=<boundary-string>
Body
    user_name: "<usr>"
    password: "<pwd>"
    provider_name: "<provider>"     # optional

POST {MAGPIE_URL}/signin
Headers
    Content-Type: application/x-www-form-urlencoded
Body
    user_name=<usr>&password=<pwd>&provider_name=<provider>

POST {MAGPIE_URL}/signin
Headers
    Content-Type: application/json
Body
    {
        "user_name": "<usr>",
        "password": "<pwd>",
        "provider_name": "<provider>"
    }

The response will contain Authentication Headers detail needed for user identification.

Authentication Providers

For any of the Authentication requests, omitting the provider_name identifier (or explicitly using value of MAGPIE_DEFAULT_PROVIDER) will default to employ Internal Provider method. This means that User identity resolution will be attempted against locally registered users in Magpie database.

To instead use one of the External Providers, the corresponding provider identifier must be provided within the sign-in request contents with provider_name. The value of that field must be one of the available provider in the below table.

Each provider has different configuration parameters as defined in Magpie Security module and use various protocols amongst OpenID, ESGF-flavored OpenID and OAuth2. Further External Providers can be defined using this module’s dictionary configuration style following parameter specification of Authomatic package used for managing this Authentication procedure.

Category

Provider

Open Identity (OpenID)

OpenID

Earth System Grid Federation (ESGF) (1)

German Climate Computing Centre (DKRZ)

French Research Institute for Environment Science (IPSL)

British Centre for Environmental Data Analysis (CEDA) (2)

US Lawrence Livermore National Laboratory (LLNL) (3)

Swedish Meteorological and Hydrological Institute (SMHI)

OAuth2

GitHub_AuthN Authentication

WSO2 Open Source Identity Server
(1) extended variant of OpenID
(2) formerly identified as British Atmospheric Data Centre (BADC)
(3) formerly identified as Program for Climate Model Diagnosis & Intercomparison (PCMDI)

Note

Please note that due to the constantly changing nature of multiple of these external providers (APIs and moved Websites), rarely used authentication bridges by the developers could break without prior notice. If this is the case and you use one of the broken connectors, summit a new issue.

Using any of the External Providers will tell Magpie to interrogate the configured identity URL of that provider and use the credentials to attempt Authentication. If successful, the response returned by that Provider should be parsed by Magpie in order to determine which corresponding local User profile it refers to. After validation, the Logged User will be Authenticated and following requests will be applicable using the same Cookie methodology as when using normal local provider procedure. See Authentication Headers for more details on that matter.

Authentication Headers

New in version 3.9: The WWW-Authentication and Location-When-Unauthenticated headers are returned whenever the HTTP Unauthorized [401] response is the result of a request. This is done in order to help requesting users or applications identify the endpoint where it can attempt Authentication with credentials.

After execution of an Authentication request, a Set-Cookie header with Magpie user identification token named according to Security Settings should be set in the response as follows.

Set-Cookie: {MAGPIE_COOKIE_NAME}=<auth-token>!userid_type:int;
            [Domain=<domain>; Path=<path>; HttpOnly; SameSite=Lax; Max-Age=<seconds>; expires=<datetime>]

Web browsers and libraries for HTTP requests handling should automatically detect that header and register the defined Cookie for subsequent requests. Alternatively, that Cookie can be provided directly in the request using the same format.

All additional parameters (in brackets above) are optional and can be provided to explain how control of the scope the Magpie cookie applies to, notably to avoid conflicts with other potential cookies employed by the request. The only mandatory parts are the MAGPIE_COOKIE_NAME value, the actual token value, and the indication of represented content with !userid_type:int to let Magpie known the provided token information is employed to resolve the Logged User by ID.

Note that any Cookie generated by Magpie can have a maximum valid duration, identified by the both the returned Max-Age in seconds and the expires value as explicit date and time. Generated cookies are defined in such a way that they will automatically emit a new Cookie based on reissue time after 1/10th of the Max-Age to update the Cookie over continuous sessions. Any Logged User will therefore remain logged in if further requests are accomplished using the same Cookie within the lifetime duration of the original login, unless explicitly logged out. Modifications of the duration is accomplished using configuration detailed in Security Settings.

Changed in version 3.9: Although maximum duration could be defined in settings, prior versions did not explicitly indicate them in the generated Cookie. Following versions without these values will effectively mean the Cookie has unlimited lifetime.

As for most of the other API request endpoints offered by Magpie, the Accept header can be provided to select the format of the desired returned content. Following valid Authentication, the body should contain a basic message indicating as such, and returning OK [200] status. Otherwise, the appropriate HTTP error code will be returned with a description message of the error cause. By default, header definition Accept: */* or completely omitted value for Accept will employ application/json for the returned Content-Type.

Authorization Headers

Following any successful Authentication request as presented in the previous section, the obtained Cookie defines which Logged User attempts to accomplish an operation against a given protected URI. Magpie employs the same Cookie both for operations provided by its API and for accessing the real Resource protected behind the Proxy according to resolution of Effective Permissions based on Applied Permissions definitions.

Access to Magpie Operations

When a Logged User has sufficient Permissions, it will be allowed different levels of access to operate onto Magpie API paths. The specific requirements for each case are extensively presented in section Route Access.

Access to Protected Resources

When sending requests to the Policy Enforcement Point (e.g.: Twitcher Proxy), appropriate Cookie headers must be defined for it to identify the Logged User and resolve its Effective Permissions accordingly. Not providing those tokens will default to using MAGPIE_ANONYMOUS_USER, which will result into either one of HTTP Unauthorized [401] or Forbidden [403], depending on how the PEP interprets and returns the response indicated by Magpie, unless the corresponding Resource was allowed for Public Access.

When appropriately authenticated, access to the targeted Resource will be granted or denied depending on the Effective Permissions that Logged User has for it. This decision is extensively explained in section Permissions Resolution.

Another alternative to obtain Authorization (only when using the utilities_adapter) is by providing the Authorization header in the request with appropriate credentials. In this situation, the adapter will attempt a login operation inline to that original request, and if successful, will update the Cookie headers accordingly. Although this method saves the need for the client to explicitly do an initial Authentication request toward Magpie’s signin path prior to Resource access attempt, failing to update the following any following requests with the Cookie will repeat the procedure on each call, which will slow down response time. If multiple requests are executed, especially for accessing different protected resources, Authentication Requests should be employed instead to process Authentication only once.

The format of the Authorization header is has follows.

Authorization: Bearer <access_token>

Where the access_token must correspond with the applicable provider_name specified by query parameter in order to orchestrate the Authentication operation accordingly. Once again, omitting the provider_name will default to User identification against local accounts in Magpie using MAGPIE_DEFAULT_PROVIDER.

Todo

Support Authorization: Basic <base64-user-pass> (see #255)