Spinnaker out of the box is not pre-configured to be secure within AWS and does not automatically provide authorization. Here’s how to secure Spinnaker in AWS using OAuth 2.0.

This configuration leverages GitHub OAuth 2.0 (including GitHub Enterprise), but if you prefer to use Okta, Google, Azure, Facebook or other OAuth 2.0 you can modify the second configuration step below for those providers.

The process below requires manual modification of YAML files. If you’d prefer to have a more streamlined, automated way of securing Spinnaker in AWS, we’ll be introducing this functionality into Armory Spinnaker v1.0 very soon. Email us or subscribe if you’d like to be notified when this is available.

**Setting up GitHub OAuth 2.0 with a Secured Spinnaker in AWS is a two step process:**

Step 1: Secure Spinnaker in AWS, which has the following prerequisites:

  • You must have an SSL cert for your site already set up in AWS for use on an ELB.
  • You must have the cert loaded into a Java Keystore file (*.jks)
  • We have tested this process against the following versions:
    - Gate:v2.96.0
    - Deck:v2.921.0

This is how you'll want to set up the ELB:

  • HTTPS:9000 → HTTP:9000.
  • Notice that this is HTTPS to HTTP, effectively terminating the SSL here. This means you'll need to use the cert mentioned in the prerequisites on this ELB.
  • TCP:8084→TCP:8084
  • There's no need to worry about SSL termination at the ELB since it's necessary for Gate to take care of this itself.

Now that the ELB is configured, you'll want to configure Gate on the Spinnaker instance.

Copy the Java Keystore file to /opt/spinnaker/config/keystore.jks and note the keystore password and the alias for your cert within the keystore.

Then create the file: /opt/spinnaker/config/gate-local.yaml
with the following contents:

    server:
      ssl:
        enabled: true
        keyStore: /opt/spinnaker/config/keystore.jks
        keyStorePassword: keystore-password-here
        keyAlias: cert-alias-here

Edit the following fields in /opt/spinnaker/config/spinnaker-local.yaml

    
    
    services:
      gate:
        baseUrl: https://${HOSTNAME}:8084
    
      deck:
        baseUrl: https://${HOSTNAME}:9000
        gateUrl: https://${HOSTNAME}:8084

The HOSTNAME environment variable will be filled out by the next step.

The following variables need to be added to the environment running Spinnaker:

HOSTNAME=your-spinnaker-elb-hostname-here
API_HOST=https://${HOSTNAME}:8084

If you're using an environment file like /etc/default/spinnaker, just add the lines above to that file.

Once you've completed the steps above, restart Gate. Test it by going to https://your-spinnaker-elb-hostname-here:8084 and ensure the SSL certs are working correctly.

You're halfway there! Communication with Spinnaker is now secure. Crack open a frosty beverage of your choice and continue below.

Step 2: Set up authorization with the OAuth 2.0 provider

Here are instructions to use GitHub OAuth 2.0 as a single sign on method. Authorization will then be checked against the GitHub API. The configuration below is for GitHub or GitHub Enterprise, but other possible configurations include Azure OAuth, Okta, Google or Facebook.

First, setup the OAuth2 app in GitHub.

  • Replace yourdomain in the blue box "Homepage URL" above with hostname of Deck
  • For the "Authorization callback URL," in blue replace yourdomain with your Gate hostname.
  • Make sure to use HTTPS for both URLs above.

Next, generate a personal API access token. It only needs to have read:org permissions. (You might want to create a GitHub Bot account for this and add it to your organization). This token will be used to ensure that the OAuth users are actually part of the Organization.

Now for the home stretch: Add the GitHub configuration above to Gate by creating /opt/spinnaker/config/gate-githubOAuth.yml :

spring:
      oauth2:
        client:
          clientId: xxxxxxxxxxxxxxxxx83a
          clientSecret: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx722
          userAuthorizationUri: https://github.com/login/oauth/authorize # Used to get an authorization code
          accessTokenUri: https://github.com/login/oauth/access_token # Used to get an access token
          scope: read:org,user:email
        resource:
          userInfoUri: https://api.github.com/user # Used to the current user's profile
        userInfoMapping: # Used to map the userInfo response to our User
          email: email
          firstName: name
          lastName:
          username: login
    auth:
      groupMembership:
        service: github
        github:
          organization: your-org-here
          baseUrl: https://api.github.com
          access_token: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx2a0    

The fields to fill in are the clientID and clientSecret from the yellow box in the first screenshot above. Also fill in the GitHub Organization you want to authorize by replacing your-org-here with your Organization name. Only users in this Organization will have access to Spinnaker. Finally, add the access_token you generated in the previous step.

Now, to enable auth within Spinnaker, edit the following field in /opts/spinnaker/config/spinnaker-local.yml :

    services:
      deck:
        auth:
          enabled: true

Lastly, as in Step 1, add variables to the environment running Spinnaker by modifying whichever environment file you are using -- probably /etc/default/spinnaker :

    GATE_OPTS="-Dspring.profiles.active=local,githubOAuth"
    AUTH_ENABLED=true
    AUTH_ENDPOINT=https://${HOSTNAME}:8084/auth/user

Restart Gate and Deck, and you're done. You can rest easy knowing that Spinnaker is now secured in AWS using GitHub OAuth 2.0 and everyone at your company will consider you a hero!

Learn More