GitHub

# Setting up MIRACL Trust SSO as an Identity Provider Within GitHub

These instructions are up-to-date at the time of writing, but you should refer back to the GitHub page on SAML IdP access to check for any changes. We cannot guarantee the accuracy of our SP-specific guidance. Username considerations with SAML: GitHub Enterprise usernames can only contain alphanumeric characters and dashes (-). GitHub Enterprise normalizes any non-alphanumeric character in your account’s username into a dash. For example, a username of ‘gregory.st.john’ are normalized to ‘gregory-st-john’. Note that normalized usernames also can’t start or end with a dash. They also can’t contain two consecutive dashes.

Open the Management Console (visit Accessing the Management Console for instructions on how to do this).
Click on Authentication in the left sidebar:
Select SAML.
If you want to enable unsolicited response SSO, select IdP initiated SSO.

We recommend keeping this value unselected. You should enable this feature only in the rare instance that your SAML implementation does not support service provider initiated SSO.
Select Disable administrator demotion/promotion if you don’t want your SAML provider to determine administrator rights for users on your GitHub Enterprise instance.
In the Single sign-on URL field, type the HTTP or HTTPS endpoint on your IdP for single sign-on requests. This value is provided by your IdP configuration. If the host is only available from your internal network, you may need to configure your instance’s DNS to use internal nameservers.
Optionally, in the Issuer field, type your SAML issuer’s name. This verifies the authenticity of messages sent to your instance.
In the Signature Method and Digest Method drop-downs, choose the hashing algorithm used by your SAML issuer to verify the integrity of the requests from your instance.
Find the MIRACL Trust metadata document – you should have downloaded this as an XML file (available at the following endpoint: http://<yourssoip>/metadata). Note that, for a production setup, if you manually download your IdP metadata file, the validUntil date at the top of the file needs to be edited to an appropriate date (it defaults to 48hrs from the current date).
Under Verification certificate (replace existing), click Choose File and browse to the XML file referred to in step 9 (above).

# Configuring Your GitHub Service Provider Profile With MIRACL Trust SSO

Edit /etc/miracl-sso/service_providers/github.yaml:

profile:
  nameid:
    github: >-
      <NameID NameQualifier="{{.MetadataEntityID}}" SPNameQualifier="{{.SPEntityID}}" Format="urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified">{{.SessionUserName}}</NameID>
sp:
  github:
    description: Github
    name: Github
    relay_state: ""
    login_url: http://github.example.com
    logout_url: http://github.example.com/logout
    metadata: >-
      <!-- insert downloaded SP metatadata here -->
    sign_response: false
    sign_assertion: true
    encrypt_assertion: false
    authorize:
    - - email: ^[^@]+@example.com$
    profile:
      nameid: github
      attribute: empty

Update login_url and logout_url with the correct values from GitHub.
The Github SP metadata is available from https://<yourgithubissuerurl>/saml/metadata and should be pasted into the above metadata field.

Note that, if you are using JSON format for your config file, the downloaded metadata should be saved as an xml file and converted to a single line with the " characters escaped with \ to meet json structure requirements. This can be achieved by running the following command on the downloaded metadata.xml file:
```
echo -e "\n"$(cat metadata.xml | tr -d '\n' | sed -E 's/"/\\"/g')"\n"
```
The contents then are output in the terminal in a format that can be pasted into the metadata field of a JSON file.
In the authorize subsection, you can control what users are allowed to attempt login by following one or both of the below steps:
- Call up an LDAP setup from an ldap.yaml file stored in /etc/miracl-sso/integrations.
- Configure a regex list of email addresses/domains. The above config shows an example of how you would use email: ^[^@]+@example.com$ to only allow users from a certain email domain to login.
Note that if this is not set correctly, you receive ‘unauthorized user’ messages.

For more detailed info on using LDAP, API and/or regex to control authorized users, please see the authorization menu section.
Save and close the file.
In your /etc/miracl-sso/config.yaml file make sure you add github.yaml to the list of ‘includes’:
```
includes:
  - core.yaml

# service providers
  - service_providers/github.yaml
```
As always after config changes, restart the server.
Now your service is configured, you can visit https://<yourssoip>/login/github or https://<yourssoip>/services to log in to the service using IdP-initiated login, or visit the Github login page and SP-initiated login are triggered automatically.
You are able to login using the in-browser PIN pad or with the MIRACL Trust app. When logging in to your SSO service for the first time you are asked to register an email address so as to confirm your identity and register you as a user.