fab-manager/doc/sso_with_github.md

How to configure Fab-manager to use a Single Sign-On authentication?

For this guide, we will use GitHub as an example authentication provider, because it uses OAuth 2.0 which is currently implemented in Fab-manager, it has a standard implementation of the protocol and it is free to use for everyone.

• First, you must have a GitHub account. This is free, so create one if you don't have any. Visit https://github.com/join?source=login to create an account.

• Go to your Fab-manager's instance, login as an administrator, go to Users management and Authentication. Click Add a new authentication provider, and select OAuth 2.0 in the Authentication type drop-down list. In name, you can set whatever you want, but you must be aware that:

  1. You will need to type this name in a terminal to activate the provider, so prefer avoiding chars that must be escaped.
  2. This name will be occasionally displayed to end users, so prefer sweet and speaking names.

• You'll see an "Authorization Callback URL" field, generated based on what you typed previously. Copy the content of this field to your clipboard.

• Now, you will need to register your Fab-manager instance as an application in GitHub. Visit https://github.com/settings/applications/new to register your instance.

  • In Application name, we advise you to set the same name as your Fab-manager's instance title.
  • In Homepage URL, put the public URL where your Fab-manager's instance is located (eg. https://example.com).
  • In Authorization callback URL, you must paste the URL previously copied from Fa-manager.

• You'll be redirected to a page displaying two important information: your Client ID and your Client Secret. Keep them safe, you'll need them to configure Fab-manager.

• Now go back to your Fab-manager's configuration interface and fulfill the remaining form with the following parameters:

  • Server root URL: https://github.com This is the domain name of the where the SSO server is located.
  • Authorization endpoint: /login/oauth/authorize This URL can be found here.
  • Token Acquisition Endpoint: /login/oauth/access_token This URL can be found here.
  • Profile edition URL: https://github.com/settings/profile This is the URL where you are directed when you click on Edit profile in your GitHub dashboard.
  • Client identifier: Your Client ID, collected just before.
  • Client secret: Your Client Secret, collected just before.

Please note the common URL must only contain the root domain (e.g. http://github.com), and the other parts of the URL must go to Authorization endpoint (e.g. /login/oauth/authorize) and Token Acquisition Endpoint (e.g. /login/oauth/access_token).

• Then you will need to define the matching of the fields between the Fab-manager and what the external SSO can provide. Please note that the only mandatory field is User.uid. To continue with our GitHub example, you will need to look at this documentation page to know witch field can be mapped and how, and this one to know the root URL of the API.

  • Model: User
  • Field: uid
  • API endpoint URL: https://api.github.com/user Here you can set a complete URL OR only an endpoint referring to the previously set Common URL.
  • API type: JSON Only JSON API are currently supported
  • API fields: id According to the GitHub API documentation, this is the name of the JSON field which uniquely identify the user.

  Once you have completed and validated the mapping's line, an information button will be available. A click on it will show you the type of data expected from the API and, in some cases, you'll be able to configure a transformation. For example, the Profile.gender field require a boolean attribute but your API may return strings like man / woman. In this case, you'll be able to configure a transformation for man <-> true and woman <-> false.

  Now, you are free to map more fields, like Profile.github to html_url, or Profile.avatar to avatar_url...

• Once you are done, your newly created authentication provider, will be marked as Pending in the authentication providers list. To set it as the current active provider, you must open a terminal on the hosting server (and/or container) and run the following commands:

# replace GitHub with the name of the provider you just created
rails fablab:auth:switch_provider[GitHub]

• As the command just prompted you, you have to re-compile the assets
  • In development, rails tmp:clear will do the job.
  • In production with Docker, rm -rf public/packs, followed by docker-compose run --rm fabmanager bundle exec rails assets:precompile
• Then restart the web-server or the container.
• Finally, to notify all existing users about the change (and send them their migration code/link), run:

rails fablab:auth:notify_changed