GitHub

Before You Begin

Introduction

This document describes how to configure Oracle Identity Cloud Service to provide Single Sign-On (SSO) for GitHub using SAML.

About GitHub

GitHub is a web-based Git or version control repository and Internet hosting service. It offers all the distributed version control and source code management (SCM) functionalities of Git. It provides access control and several collaboration features such as bug tracking, feature requests, task management, and wikis for every project.

After integrating GitHub with Oracle Identity Cloud Service:

  • Users can access GitHub using their Oracle Identity Cloud Service login credentials.
  • Users can start GitHub using the Oracle Identity Cloud Service My Apps console.
  • Admins can assign and revoke user access to the GitHub app using the Oracle Identity Cloud Service administration console.

What Do You Need?

  • An Oracle Identity Cloud Service account with authorization rights to manage apps and users (Identity Domain Administrator or Application Administrator).
  • A GitHub account with authorization rights to configure federated authentication.
  • Service Provider Signing certificate
  • A virtual or local machine with the GitHub Enterprise Appliance software installed to enable SSO for GitHub. Note: Make note of the host name that you specify during installation. For instance, git.example.com. Use this host name value as a domain name later in the "Obtaining Service Provider Signing Certificate in .PEM Format", "Registering and Activating the GitHub App", and then "Configuring SSO for GitHub" sections.

Configuring the GitHub App in Oracle Identity Cloud Service

Use this section to register and activate the GitHub app, and then assign users to the app.

Obtaining Service Provider Signing Certificate in .PEM Format

Use this section to convert the Service Provider Certificate value into a format that is suitable for Oracle Identity Cloud Service.

Tip: Use this .PEM format certificate later during the GitHub configuration in the "Registering and Activating the GitHub App" section.

  1. Use the following URL to access the service provider metadata: https://<Domain_Name>/saml/metadata.

    Note: Domain Name is the value that you specified as the host name during installation of the GitHub Enterprise Appliance. See the "What Do You Need" section.

  2. In the metadata file, locate the md:SPSSODescriptor tag.

  3. Copy the content between the ds:X509Certificate tags into an MS-Word document. This content is the Service Provider Signing certificate.

    Image img1.png displays the metadata content with md:SPSSODescriptor and ds:X509Certificate tags highlighted.

  4. Access the URL: https://www.samltool.com/base64.php to convert the certificate to .PEM format. The Base64 page appears.

  5. Locate the Decode section, paste the content in the XML to be Base64 Decode text box, and then click BASE64 DECODE XML. The converted certificate content is displayed in the Base64 Decoded XML text box.

  6. Copy the content from the Base64 Decoded XML text box, paste the content in a text file, and then save the file in .PEM format.

    Tip: Use this file later during registering the GitHub app in the "Registering and Activating the GitHub App" section.

Registering and Activating the GitHub App

  1. Access the Oracle Identity Cloud Service administration console, select Applications, and then click Add.

  2. Click App Catalog.

  3. Search for GitHub, and then click Add.

  4. In the App Details section, enter your GitHub Domain Name, and then click Next.

    Note: Domain Name is the value that you specified as the host name during installation of the GitHub Enterprise Appliance. See the "What Do You Need" section.

  5. In the SSO Configuration section, Click Download Signing Certificate.

    Tip: Use this file later during GitHub configuration in the "Configuring SSO for GitHub" section.

  6. Click Download Identity Provider Metadata.

    Tip: Use this file later during GitHub configuration in the "Configuring SSO for GitHub" section.

  7. Expand the General Settings section, and then upload the signing certificate of the service provider that you obtained earlier. See the "Obtaining Service Provider Signing Certificate in .PEM Format" section.

  8. Click Finish. Oracle Identity Cloud Service displays a confirmation message.

  9. Click Activate, and then click Activate Application. Oracle Identity Cloud Service displays a confirmation message.

Assigning Users to the GitHub App

  1. On the GitHub app page in Oracle Identity Cloud Service, select Users, and then click Assign. The Assign Users window appears.

  2. Select users that you want to assign to GitHub, and then click OK. Oracle Identity Cloud Service displays a confirmation message stating that the GitHub app is assigned to the users that you selected.

Configuring SSO for GitHub

  1. Access GitHub as an administrator using the URL: https://<Domain_Name>/setup/settings. The GitHub Settings page appears.

    Note: Use the host name that you specified during installation of the GitHub Enterprise Appliance. See the "What Do You Need" section.

    Image img3.png displays the address bar of the GitHub home page with the HostName field highlighted in the URL.

  2. In the left navigation menu, select Hostname, enter the host name that you used in the Login URL, and then click Test domain settings to validate the host name.

  3. In the left navigation menu, select Authentication, and then select SAML.

  4. In the Authentication section, use the table to update the federated authentication attributes, and then click Save settings.

    This table lists the mandatory federated authentication attributes that you must set to complete the SSO configuration.
    Attribute Value
    Single sign-on URL Enter the Sign-in URL/SSO Endpoint: https://<IDCS-Service-Instance>.identity.oraclecloud.com/fed/v1/idp/sso.
    Issuer Enter the Entity ID/Issuer URL. Use the metadata file that you downloaded earlier to obtain the Entity ID/Issuer URL. The Entity ID/Issuer URL information is located in the first line of the metadata. See the "Registering and Activating the GitHub App" section.
    Signature Method Select RSA-SHA1 from the drop-down list.
    Digest Method Select SHA1 from the drop-down list.
    Upload Certificate Upload the certificate that you downloaded during GitHub registration in Oracle Identity Cloud Service. See the "Registering and Activating the GitHub App" section.

    Note: The GitHub app can be accessed by a user who is assigned to the GitHub app in Oracle Identity Cloud Service, even if the user does not have a GitHub account.

Verifying the Integration

Use this section to verify that SSO works when initiated from Oracle Identity Cloud Service (IdP initiated SSO) and GitHub (SP initiated SSO).

Verifying Identity Provider Initiated SSO from Oracle Identity Cloud Service

  1. Access the Oracle Identity Cloud Service My Profile console using the URL: https://<IDCS-Service-Instance>.identity.oraclecloud.com/ui/v1/myconsole.

  2. Log in using credentials for a user that is assigned to the GitHub app. Oracle Identity Cloud Service displays a shortcut to GitHub under My Apps.

  3. Click GitHub. The GitHub home page appears.

  4. In the upper-right corner of the header, click the user ID drop-down list, and then confirm that the user that is logged in is the same for both GitHub and Oracle Identity Cloud Service.

    This confirms that SSO that is initiated from Oracle Identity Cloud Service works.

Verifying Service Provider Initiated SSO from GitHub

  1. Access GitHub using the URL: https://<Domain_Name>. You are redirected to the Oracle Identity Cloud Service login page.

  2. Log in using credentials for a user that is assigned to the GitHub app. The GitHub home page appears.

  3. In the upper-right corner of the header, click the user ID drop-down list, and then confirm that the user that is logged in is the same for both GitHub and Oracle Identity Cloud Service.

    This confirms that SSO that is initiated from GitHub works.

Troubleshooting

Use this section to locate solutions to common integration issues.

Known Issues

Oracle Identity Cloud Service displays the message, "You are not authorized to access the app. Contact your system administrator."

Cause 1: The SAML 2.0 integration between the Oracle Identity Cloud Service GitHub app and GitHub is deactivated.

Solution 1:

  • Access the Oracle Identity Cloud Service administration console, select Applications, and then select GitHub.
  • In the App Details section, click Activate, and then click Activate Application. Oracle Identity Cloud Service displays a confirmation message.

Cause 2: The administrator revokes access for the user at the same time that the user tries to access the GitHub app using Oracle Identity Cloud Service.

Solution 2:

  • Access the Oracle Identity Cloud Service administration console, select Applications, and then select GitHub.
  • In the App Details section, select Users, and then click Assign to re-assign the user.

Unknown Issues

For unknown issues, contact Oracle Support:

  1. Go to https://support.oracle.com.

  2. Select Cloud Support, and then sign in with your support credentials.

  3. In the Cloud Dashboard, confirm that there are no planned outages in Oracle Identity Cloud Service, and then click Create Service Request.

  4. Select Oracle Identity Cloud Service as the service type.

  5. Complete your service request.