Setup OAUTH2 on ADFS 3.0

Windows

In this article i will go over how to setup your ADFS 3.0 (available in Windows Server 2012 R2) server for OAUTH2 authentication.

A couple of things to note:

  • This setup will work for both standalone and farm deployments (including using the WID database). This is because Microsoft build an OAuth Authorization Code Lookup Protocol so that if one server generates the token you can claim it from another in the farm (when using standalone artifact store): https://msdn.microsoft.com/en-us/library/dn409270.aspx
  • Make sure you have a basic ADFS configured, there are plenty of guides like this one: https://technet.microsoft.com/en-GB/library/dn486820.aspx
  • ADFS 3.0 does not support secrets or token encryption/decryption for OAUTH2
  • While OAUTH2 is a standardized protocol i would not call Microsoft implementation a straight forward or standardized solution as there are some specifications.
  • If you are using a self-singed certificate please make sure that:
  • Make sure when you open the certificates in the AD FS console there are no errors
  • I have used SHA 256 RSA Certificates and they work great.

!!!Warning!!! – If you use 512 Certificates you will experience issues on ADFS and with OAUTH2.0. You will need to disable TLS1.2 as it doesn’t support 512. You may see errors as show below in the AD FS Admin error log:

Event ID: 36874– TLS 1.2 connection request was received from a remote client application, but none of the cipher suites supported by the client application are supported by the server. The SSL connection request has failed.

Here is some information you will need before we begin:

  • ClientID : you can either come up with this or just use a generator like : https://www.guidgenerator.com/online-guid-generator.aspx
  • Redirect URI : depending on the application you use and the domain this value will very so please check the application documentation (basically where the browser needs to be redirect after the authentication completes)
  • Relaying party identifier: in most cases you will make this up, i recommend using the application domain eg.(https://www.myapp.com)
  • The Claims: This would be what values you require to return back to the application, check with the application documentation.

After you are done you will need to make a note of the following things in order to configure your application:

  • ClientID
  • Redirect URI
  • Auth Endpoint : this would be https://myadfs.com/adfs/oauth2/authorize (replace myadfs with whatever domain you have configured)
  • Token Endpoint : this would be https://myadfs.com/adfs/oauth2/token (replace myadfs with whatever domain you have configured)
  • The public key (the cert without the private key) of the root CA of your Service Communications Certificate. You can export this and add it to your application server Trusted Root Certification Authorities. This is need for a successful TLS communication.
  • The public key (the cert without the private key) of your signing certificate. Usually you will need this in PEM or CRT format so you may need to convert it. This will be needed if you or the application you are using needs to verify the JWT token signature (strongly recommended).

Lets go into our ADFS server console and first configure our Relying Party Trust:

adfs1

adfs2

adfs3

Now give our Relying Party Trust a meaningful name

adfs4

adfs5

Leave the next section blank as ADFS3 OAuth2 does not support encryption

adfs6

Again we leave it blank as we don’t use SAML or WS

adfs7

now we need to enter our Relaying party identifier

adfs8

If you need multi factor then configure it if not skip it

adfs9

adfs10

 

Once that is done you can configure your Claims (Issuance Transform Rules) whatever they may be

 

Once done we need to configure our endpoints and we do this via Powershell with the following command:

We specify some of the variables you collected before hand and then give it a meaningful name

 

I also recommend you set the option “EnableJWT” to true on the Relying Party Trust you configured by running:

 

And that should be it, you should be able to now use the OAUTH2 function with your app.

Enable ADFS OAUTH2 for Mattermost 2.1

Mattermost

 

 Please note, we have released a new version for Mattermost 3.0.2

Enable ADFS OAUTH2 for Mattermost 3.0

So we had a request a few weeks ago to get Mattermost 2.1 working with ADFS so we can use SSO. Unfortunately for us no one had coded a version that can work with ADFS, so we took on the challenge. After two weeks and lots of trials and errors we had designed a secure version ( Mattermost 2.1.1) that worked with ADFS. This version is based on the the March 16, 2016 stable release v2.1.0 of Mattermost.

The advantages of using ADFS over other methods:

  • True SSO
  • Much more secure then LDAP or gitlab with LDAP
  • Proven for Enterprise

We have also made sure that the following features are available:

  • Other domains and forest can also use Mattermost if invited and trusts exists
  • Authentication is based on AD SID so if a user is deleted or leaves the company a new user with the same domain username will get a new account with a different username. This is very important as it insures that users are unique and that even if you have two users with the same usernames in different domains they will each get there unique username and not effect one another.

Here is the guide on where to get it and how to configure it:

adfsm1 adfsm2 adfsm3 adfsm4

You will first need to download/compile and install the new version which can be found below:

You can download the compiled version from: http://www.gi-architects.co.uk/wp-content/uploads/2016/04/mattermost.tar.gz or form https://github.com/lubenk/platform/releases

You can get the code from: https://github.com/lubenk/platform/tree/ADFS-2.1.1

 

Now that you have a working copy it’s time to configure ADFS 3.0 for OAUTH2.0 please use the instructions on : http://www.gi-architects.co.uk/2016/04/setup-oauth2-on-adfs-3-0/

with the following additions notes:

ClientID : Just generate one at https://www.guidgenerator.com/online-guid-generator.aspx (please make sure this guid is either more then or less then 26 characters).
Redirect URI : https://mattermost.local/signup/adfs/complete (where mattermost.local is the dns address of your mattermost app)
Relaying party identifier: you can just use your dns address of your mattermost app

The following Claim setup, please make sure the claims are exact, the rules name can be anything:

adfsm7

adfsm5

adfsm8

adfsm6

 

Once you setup adfs you need to configure mattermost, you can either do this via the config.json or via the admin interface as show below:

adfsm4

Please make sure you copy the public key of the ADFS root CA of your Service Communications Certificate in PEM format (the format that has —-BEGIN CERTIFICATE—- in it) into /usr/local/share/ca-certificates and name it with a .crt file extension, then run “sudo update-ca-certificates”.

You also need the public key of the signing certificate in PEM format somewhere on the server which you will need to reference in the settings.

And that is it you should have a working version with ADFS