OpenID Connect authentication configuration

Page is a Work In Progress

Using OpenID Connect

OpenID Connect is an authentication layer on top of OAuth 2.0 framework. Major authentication providers like Google and Azure already have support for it.

1. Setting up UI authentication
   1. Prerequisites
   2. Registering application
   3. Configure FOSSology
   4. Test login
   5. Disabling username-password login
2. Setting up REST API authentication
   1. Benefits of M-2-M token over Bearer tokens
   2. Register with authentication provider
   3. Registering client with FOSSology
   4. Generating token
   5. Verify client id claim
   6. Test connection
   7. Restrict REST API token type

Setting up UI authentication

For the following process, we are using Auth0 as an authentication provider. However, except for the registration process, everything else should be same for all providers.

Prerequisites

1. A provider which supports OpenID Connect Authorization Code Flow (Auth0 for example)
2. Network connectivity with provider from the server (server will make some GET and POST requests to the provider)
3. Administrative account on FOSSology

Registering application

1. Signup with Auth0 and add a new application as "Regular Web App":
2. Goto application "Settings" and fill out basic information.
3. Add "Application Login URI" and "Allowed Callback URLs" to point to your FOSSology homepage.
4. Add the server domain to "Allowed Web Origins" and "Allowed Origins (CORS)".
5. Under application setting, goto bottom in Advance Settings and make sure "Authorization Code" Grant Type is checked.
6. Under Applications, goto APIs and copy the "API Audience" URL.
   • Paste this copied URL in your account settings as "Default Audience".
   • Without this step, Auth0 generates a proprietary access token and break the application.

Configure FOSSology

1. Login to FOSSology and head over to "Admin > Customize".
2. Find following fields and fill them.
   • OIDC App Name: The name shown on login button.
   • OIDC Client Id: "Client ID" from Auth0
   • OIDC Secret: "Client Secret" from Auth0
   • Redirect URL: This will be the callback URL (the URL where app is hosted).
     • Make sure the redirect URL matches callback URL in Registering application section.
   • OIDC Discovery URL: Available under "Advanced Settings > Endpoints" as "OpenID Configuration".
3. Hit "Update" to save the changes. FOSSology will try to pull other URLs from the Discovery URL. Make sure all fields are filled.
   • "Logout URL" is optional and is used to redirect user once they logout.
4. If some of the fields are not populated from discovery url, make sure to fill them manually. All the fields (except Logout URL) are required for OIDC to work.
   • The "OIDC Client Id Claim" is required for REST API authentication and is explained in Verify client id claim section bellow.

Test login

1. Create a user in Auth0 under "User Management".
2. Create user with the username as email entered in Auth0.
   • The current authentication mechanism gets the email of user from auth provider and create a session for the user with same username.
3. Logout if you are currently logged in and there should be additional button "Login with (OIDC App Name)" like bellow.
4. Try to login with the new button. If there are any errors, they will be mentioned at the message space in UI.

Disabling username-password login

Once OIDC login is setup on the instance, the password based login can be disabled.

1. Open the /etc/fossology/fossology.conf or /usr/local/etc/fossology/fossology.conf file.
2. Find the [AUTHENTICATION] section and modify provider to external.
   • Doing so, users will no longer be allowed to use their passwords for login.
3. To revert, simply change the value of provider to password.

Setting up REST API authentication

Currently FOSSology uses Bearer tokens for REST API authentication. But with OIDC integration, it can be replaced with OpenID Connect Machine-to-machine tokens.

Benefits of M-2-M token over Bearer tokens

Topic	OIDC	FOSSology
Standard	OAuth 2.0's Client Credentials Grant	Does not follow any standard
Life span	Granularity in seconds	Upto 30 days (increment of 1 day)
Verification	JWT verification (typically with certificates)	Secure key stored with FOSSology DB
Authority	Trusted party	FOSSology server
Generating new token	Client id and secret (can be changed anytime)	FOSSology username and password (mostly static)

With all these benefits and OAuth 2.0 being a standard protocol, accessing FOSSology's REST API will be more easier and secure.

Register with authentication provider

1. From the auth provider, register a new "Machine to Machine Application". All providers should provide it under "Client Credentials" grant.
2. Select your default API and give permission "read:clients" and Authorize. For other providers, this step is optional.
3. Note the "Client ID", "Client Secret" and "OAuth Token URL" (under Settings > Advanced Settings > Endpoints). You will require this to generate tokens for your client.

Registering client with FOSSology

Since "Client Credentials" does not provide information about the user, FOSSology can not authorize the request. To do so, we can make use of client id to setup the link between user and token as most auth provider inject the client id in the access token.

1. Make sure OIDC tokens are allowed in fossology.conf.
   • Open the /etc/fossology/fossology.conf or /usr/local/etc/fossology/fossology.conf file.
   • Find the [AUTHENTICATION] section and modify resttoken to oauth or both.
2. As the intended user, login to FOSSology and navigate to "Admin > Users > Edit User Account".
3. Find "Add new oauth client" and provide the client a name, paste the Client ID from auth provider and select a scope.
   • Note: Do copy the client id exactly from MyID Connect portal without any modifications, otherwise verification will always fail.
   • Note: One client can have only one scope and can be registered only once. Do fill the scope with care.
     
4. After clicking "Add new client", you should see following message. And clicking on "Reveal" button should display the client id as well.

Generating token

1. From Quick Start, select an implementation in your language and get the access_token.
   • It requires sending a post request to Token endpoint.
   • The request body should contain "grant_type": "client_credentials" and respective client_id and client_secret.
     
2. Response will contain the access_token which can be used while calling FOSSology API.

Verify client id claim

Different implementations of auth providers exposes client id as different claim. Check the claim used by your provider and modify the default value.

1. Copy the access token provided by the auth provider as described in Generating token section.
2. Paste it on a JWT analyzer tool like jwt.io and look for your client id in payload.
   • As seen in the screenshot bellow, the claim is azp and same should be updated.
     
3. Update the "OIDC Client Id Claim" under "Admin > Customize".

Test connection

1. Use the provided access token as the Bearer token.
2. Request the endpoint /api/v1/users/self.
3. If the request was successful and information about your user is returned, the integration was done successfully.

Restrict REST API token type

The REST API token type can be restricted based on fossology.conf.

1. Open the /etc/fossology/fossology.conf or /usr/local/etc/fossology/fossology.conf file.
2. Find the [AUTHENTICATION] section and modify resttoken. The value can be:
   • token: Allow only old JWT tokens
   • oauth: Allow only new OIDC tokens
   • both: Allow both old and new tokens

Please open an issue/discussion in case any assistance is required.