ADFS Integration

There is a 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 (this is not complete):

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 will be described later.

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.