SSO Integration

Saml 2 Protocol: A text file needs to be created and kept in the runner folder and a file named ‘FederationMetadata.xml’ (to be shared by the client) is to be placed in a folder (preferably in runner folder) and link it to the text config file that we created (Saml2.config) . The text file should include the below details.

a. IdpMetadataPath

b. NameIdFormat

c. UserNameAttribute

These details in the text file are to be added in a specific syntax and the file should be saved with the name “saml2.cofig”. 

Below, is the screenshot as an example: 

Step 2 - ‘sk.configuration’ Database Table Setup

Once sheetkraft is installed on your system a database table sk.configuration will be automatically created. You have to confirm whether the table has all values against ‘FileStorageLocation’, ‘SchedulerID’, ‘Url’. (Refer below screenshot)

By default the value against ‘Url’ will be blank or #N/A. The application url has to added against the url as value in the sk.configuration table.

Additional Information

Both the protocols have been tested against Azure AD which supports both protocols and Google which supports OAuth 2. 

SAML 2 Protocol:

The Identity Provider (Azure AD, ADFS, etc) will provide a FederationMetadata.xml file. This file has to be placed on the App Server (preferably in Runner folder). The path to this file will need to be provided in the saml2.config file. This is a new config file for SAML2

The most important decision point here is about what field to use as the username. When a user logs in using SAML2, the Identity Provider returns an "assertion". This assertion contains a NameId (unique identifier) and various attributes. SheetKraft can either set the user name to whatever is provided in NameId or to one of the attributes. We can also request a specific type of unique identifier to be returned by the Identity Provider. This should be discussed with IT. Each Identity Provider may have different names for these attributes, so these names have to be configured and mapped to the fields that SheetKraft needs.

OpenIdConnect (OIDC) protocol (Oauth2):

The OpenId Provider (OP, similar to the Identity Provider in SAML 2) will provide an issuer name. This has to be provided in oauth2.config. This is a new config file for OpenIdConnect as well as OAuth 2 connections. A ClientId and ClientSecret also shouls be provided in the config. When a user logs in using OIDC, the OP returns an IdToken, AccessToken, and RefreshToken. The IdToken is a JWT (JSON Web Token) that contains "claims". These claims contain information about the user. Each OP may name these claims differently, so the names have to be configured and mapped to the fields that SheetKraft needs.

While both protocols are supported, at this point, we should configure only one single sign on provider. Otherwise, there is a risk of usernames from one provider conflicting with the usernames from another provider and this hasn't been handled properly. In any case, within an enterprise installation, there should be no need to have multiple providers.

When we migrate an existing client from local or AD accounts to Single Sign On, we will have to discuss with IT what field to use as username. We may have to change the values in the UserName column in the sk.Users table to match the value that will come in from the SSO provider. Also the Source column will have to be changed to SSO from AD or Local. If this step is not done before users sign in with SSO, duplicate user accounts will get created.

Detailed OAuth2 flow and how it works in SheetKraft

SheetKraft configuration:

There is an oauth2.config file in Runner folder that contains information about zero or more OAuth providers. Each provider is identified by a key. In the example below we will assume that the provider is ADFS and the key is xyz.

For a given provider, we need the following information:

• Issuer: For ADFS this can be something like https://login.example.com/adfs or https://adfs.example.com. SheetKraft will attempt to fetch a json metadata file from the url obtained by appending /.well-known/openid-configuration to the Issuer url. This metadata file will contain an authorization endpoint (like https://login.example.com/adfs/oauth2/authorize/) and a token endpoint (like https://login.example.com/adfs/oauth2/token/).

• Client ID: This is some unique identifier that identifies SheetKraft. It is generated by ADFS when the SheetKraft application is registered with it.

• Client Secret: This is like a password for SheetKraft to talk to the provider. It is meant to be secret.

• LoginButtonLabel: The label for a button that is shown on the SheetKraft login page to login to the provider.

There are also other bits of information we need that are shown in the first image of this blog.

If such a config exists, the SheetKraft login page will show a button. When user click this button, a request is made via javascript to SheetKraft server which constructs an adfs url and returns it. This url looks like (newlines inserted and values not encoded for readability)

https://login.example.com/adfs/oauth2/authorize/?

client_id=______________

&response_type=______________

&scope=openid email profile offline_access

&redirect_uri=https://sheetkraft.com/sso/oidc/xyz

&response_mode=form

&state=____________________

&nonce=___________________

The javascript then sets this url in the browsers address bar causing the browser to navigate to this url. Assuming there is no cookie for the user, ADFS shows a login page with a form where user enters credentials and submits the form. The credentials then go to ADFS which validates them and returns an html page with some javascript that makes a POST request to the url https://sheetkraft.com/sso/oidc/xyz with a code and a state.

SheetKraft validates the state and makes a POST request directly to the token endpoint of ADFS with the following values in the form body

code=code obtained from the incoming POST request

client_id=______________

client_secret=______________

redirect_uri=https://sheetkraft.com/sso/oidc/xyz

grant_type=authorization_code

ADFS will provide a json response that either contains an error description or contains an access token, token expiry, and a refresh token. The access token is a JWT (Json Web Token) and contains various claims about the user who tried to sign in. To be able to use these claims, the names of these claims have to be configured in the oauth2.config file. SheetKraft will validate the signature of the token, as well as the claims and then generate its own token to indicate that the sign-in should be accepted.