Enabling SSO for your Github organization via the WSO2 Identity Server
Hello guys,
In the last #hashnote, I made a promise to you guys that I’d bring another #hashnote about how to configure SSO for Github through the WSO2 identity server. So it’s time for doing that. Before all of that, there are a few things that need to clarify first. Obviously, the first question that pops up is, what’s SSO? Simply SSO stands for the term of Single Sign-on. However, to get a proper understanding of SSO and how the WSO2 identity server can integrate for SSO solutions, please go through this article which was written by the WSO2 Solution architecture team.
Ok now back to the story. Let’s consider the following use case.
Suppose you have a tech start-up company and there are lots of employees are working as developers under your company. So Github is the best place where you can use to manage, control, and handle all the coding stuff which owns your company organization. In terms of that, all your developers need to access & manage the repositories in your GitHub organization. So it is very normal for your employees to log in to your Github organization and do the operations regularly. But in this case, all your employees use different identity providers for authenticating when log in Github organization. Some can use their Github credentials, some can use social identity providers like Google, LinkedIn for authenticating. Since the WSO2 identity server has the best identity and access management functionalities, you decide to add the WSO2 identity server as well for authenticating purposes & SSO functionalities as an IDP.
As per the above use case, now let’s look at how to configure SSO for Github with the WSO2 identity server. What you need for configuring SSO with the WSO2 identity server in your Github organization.
1- Having a Github organization within the Github Enterprise Cloud. (Here, Github Enterprise Cloud is facilitating SSO, Since other options haven’t. If you hope to use this only for testing purposes. you can take the free trial of the Github Enterprise Cloud from here).
2- The latest WSO2 identity server (You can download the latest identity server from here. This can be on-premises or cloud. Or even docker deployed identity server also fine. For this, I used an identity server docker image. You can find all the details from this).
And make sure you have admin privileges and permissions for both Git organization and Identity server. Since this #hashnote’s purpose is to explain the process from the scratch. I’ll start by creating a Github organization.
Creating a Github organization
Log into your Github profile and navigate to your profile at the top right corner. And click the “Your organizations” option. Then it will direct you to the organization page and there you can add your organization. Once you click on the “New organization” button it will prompt the options for Github subscription and choose the Github Enterprise Cloud option. If you only test this you can take the free trial option from there. However, if you already have an organization in the Github Enterprise Cloud you don’t need to worry about this step.
Now let’s configure the WSO2 identity server side.
Configure the WSO2 identity server
In this setup, the WSO2 identity server acts as the identity service provider (the IDP), and Github acts as the service provider (SP). Also, SAML is the protocol that uses in SSO. So you need to register Github as an SP in the identity server.
First, log into the management console of the identity server and add an SP as below.
Then need to do the authentication configuration and register the service provider. For that expand the Inbound Authentication Configuration section and expand the SAML2 Web SSO Configuration option since Github uses SAML protocol for SSO.
Now you can configure the mandatory fields as above image. In there, you should fill the below fields as shown below.
Issuer: https://github.com/org/{your _organization_name}
Assertion Consumer URL : https://github.com/orgs/{your _organization_name}/saml/consume.
Now you would definitely get to wonder about what are these Issuer, Assertion Consumer URLs, and other parameters. This WSO2 official document explains all about that. you can follow that for more information.
Now update the service provider registration. But make sure to download the IDP metadata file before updating, because that file will need to do the configurations on the Github side (IDP configurations).
Configure on Github
Now we have added the Github organization as an SP on the identity server side. What is left to do is to configure the WSO2 identity server as an IDP on the Github organization.
Now navigate your organization and click on the “Organization Security” at the left sidebar.
Once you click on it, it will lead you to a page where the SAML single sign-on feature is facilitating. Then tick the “Enable SAML Authentication” and It will prompt you the necessary configurations you need to make.
Before adding the Sign on URL, Issuer, and Public certificate parameters, you need to open up your downloaded IDP metadata file from the WSO2 identity server. It shows the exact details relevant to the above parameters.
Sign on URL is the Location URL which uses under “SingleSignOnService” tag in the metadata file
The issuer is the entityID in the metadata file
You should add the “X509Certificate” in the metadata file as the public certificate. but when adding that it should contain “ — — -BEGIN CERTIFICATE — — -” and “ — — -END CERTIFICATE — — -” tags. To format like this you can use this online tool.
And make sure that the Signature method algorithm and Digest method algorithm are compatible with the identity server using algorithms. By default, the WSO2 identity server is using “RSA-SHA1” & “SHA1” for the Signature method and the Digest method.
It should be as below once you are done with your configurations.
Now it’s time to test the SAML SSO configurations. Click on the “Test SAML configuration ” button. If you have done the configurations correctly it will redirect you to the identity server login page for authenticating as below.
And upon successful login, it will show messages as below.
On top of your organization page, the below message can view.
Next to the “Test SAML configuration ” button, the below message can view.
Now you successfully configured the SSO for your Github organization with the WSO2 identity server. So finally you can save all the configurations.
Further, you can enforce SAML SSO via the WSO2 identity server for all your members within this organization by enabling the “Require SAML SSO authentication for all members of the {Your_organization} organization.” option.
And since Github is not facilitating the Single log-out functionality, you need to terminate your active SAML sessions by login-out from the Identity Server.
Hope this #hashnote helps you to understand about SSO between the WSO2 identity server and Github. Please reach out to me if you got any issues when trying out this. So we will meet on another #hashnote and discuss Spring & WSO2 identity server.
Until then Happy SSO configurations…!!!
Cheers…!!!
