Skip to content
This repository has been archived by the owner on Apr 17, 2024. It is now read-only.

Home

Jump to bottom
Prachi Damle edited this page Nov 1, 2016 · 5 revisions

Auth Service in Rancher:

The rancher-auth-service listens at endpoint /v1-auth/ on <rancher_ip>:8080/v1-auth by default. This is a go micro-service that runs separately from cattle, but all requests to the service are proxied via cattle.

Code reference:

The source code is at this repo: https://github.com/rancher/rancher-auth-service

This service has implementations for two auth providers/drivers: github and shibboleth(saml)

Implementing an Access Control/Auth Provider

Auth Config:

Each access control provider has its own top-level API type for configuration specific to that type of authentication. So each provider should design the configuration model needed to configure the provider and add it to the API below.

Following is the API to be used to save the provider specific configuration to the DB:

/v1-auth/config
{
 "type":"config",
 "provider":"<name of the config enclosed(githubconfig/shibbolethconfig)>",
 "enabled":false,
 "accessMode":"unrestricted",
 "allowedIdentities":[],
 "githubconfig": {}
 "shibbolethconfig": {}
}

Checkout the https://github.com/rancher/rancher-auth-service/tree/master/model package for examples of existing configs.

Auth provider interface

Each auth provider should implement the https://github.com/rancher/rancher-auth-service/blob/master/providers/identity_provider.go interface and add the provider to the supported list of providers.

Each auth provider implementation should:

  • Define the list of setting names against which the provider config gets stored in cattle DB.
  • Provide logic to list the settings, initialize the settings from the config object
  • Encapsulate the provider specific internal implementation based on the specific protocol.
  • Provide translation from provider specific accounts/org structures to rancher model
  • Implement the provider specific token generation and lookup of identities.

Checkout the existing implementations of github/shibboleth providers under: https://github.com/rancher/rancher-auth-service/tree/master/providers

Following is a description of other rancher internal access control concepts and each individual provider does not have to implement anything for this, this is generically applied on top of auth provider implementations.

Access Modes

The authentication provider may have many users in it (i.e. the whole world, for public GitHub), so it may be desired to restrict access to Rancher to a subset of the valid users that it contains. The accessMode and allowedIdentities parameters in each driver control this.

Access Modes:

  • "unrestricted"
    • Any valid user in the auth provider can login.
  • "restricted"
    • The specific set of users/groups in allowedIdentities can login.
    • In addition, anyone added as a member of a Environment (in the UI; project in the API) can login.
  • "required"
    • Strictly the specific set of users/groups in allowedIdentities can login.
    • A member of an Environment must also be in the allowedIdentities list to login.

Enabling Access Control

The Rancher UI performs a 3-step process to safely enable access control. If you are automating and are sure the configuration is correct, you can skip the first two requests and go straight to Enabling.

Configure the desired provider

Generate a completed config object for the desired provider, with enabled: false. Submit it as the body of POST /v1/<desired provider config>.

Test the generation of an access token

POST /v1/token {code: "<code string for provider>"}

See Generating an Auth Token below for more info. If token generation fails, something is wrong with the config and you would have probably been locked out if enabled were set to true.

Enabling

Re-submit the config object to POST /v1/<desired provider config>, this time with enabled:true.

Generating an Auth Token

POST /v1/token {code: "<code string for provider>"}

For GitHub, the code string is the value sent back from the GitHub Oauth redirect. For other providers, the string is ":".

If authentication succeeds a token good for 12 hours will be returned and the configuration is working. This can be sent as an Authorization: Bearer <token> header to authenticate future requests to Rancher.

Looking up Identities

Users, groups, and/or organizations can be looked up with the /v1/identities endpoint. For most providers, GET /v1/identities will return the groups or organizations the authenticated user is a member of. Other names can be searched for with GET /v1/identities?name=<NAME>.

Managing Allowed Identities

Identities minimally consist of an externalIdType, which identifies what provider & resource type the user/group/org is, and externalId which is the specific identifier for that resource. Identities should be looked up (as above) rather than manually generated. For example in GitHub the externalId is the user/org's user_id, which is not generally well known.

In supported provider configs there is an allowedIdentities array which contains the list of allowed users/groups/orgs for "restricted" and "required" accessModes. To update the list, POST /v1/<configured provider config> with a new list. The secret parts of the config (e.g. service account passwords) can be left null to keep their current values.

Getting the currently enabled access control provider

GET /v1/token with no Authorization information sent will return the provider that is configured, along with the public pieces of information needed to use it. For example with GitHub the redirectURL which tells where to redirect the user to authenticate with github, if configured.

Disabling Access Control

POST /v1/<enabled provider config> with enabled: false

Changing Access Control providers

In general we do not recommend this. Once access control is disabled, it can be re-enabled for a different provider. Rancher has no way to know who to associate to what account to what identity when you switch providers, so the externalId/externalIdType will not be modified on existing accounts. Existing accounts and environments will no longer be accessible. This can be manually corrected in the database or the API by going through each account (/v1/accounts?kind=admin and /v1/accounts?kind=user) and editing those fields.

Clone this wiki locally