Authentication Setup

Overview

The Genesis services serve as the primary access point for all Juno products. Genesis implements authentication through the industry-standard NextAuth.js library, providing secure and reliable authentication services. Currently, Genesis supports Google and AWS Cognito as authentication providers, with more options coming soon.

This comprehensive guide walks you through the process of setting up authentication for your Genesis deployments.

Genesis Propagation

When using Genesis, it automatically detects your configured authentication services and can propagate these settings to your managed Orion deployments if you choose.

Quick Start

For production deployments, we recommend using either Google or AWS Cognito authentication. Follow the provider-specific instructions below to get started quickly.

Google Authentication

Follow these steps to set up Google OAuth for your Juno application:

1. Navigate to the Google Cloud Console
2. Create a new project or select an existing one
3. Go to APIs & Services > Credentials
4. Click Create Credentials and select OAuth Client ID
5. Select Web Application as the application type
6. Configure the application:
7. Name: [Your Application Name]
8. Authorized JavaScript origins: https://your-genesis-domain.com
9. Authorized redirect URIs: https://your-genesis-domain.com/api/auth/callback/google
10. Click Create
11. Save the generated Client ID and Client Secret for the environment configuration

AWS Cognito Authentication

AWS Cognito provides a robust user directory and authentication service. Follow these steps to configure Cognito for your Juno deployment:

1. Log in to the AWS Management Console
2. Navigate to the Cognito service
3. Click Manage User Pools
4. Create a new user pool or select an existing one
5. Go to the App Integration tab
6. Click Create app client
7. Configure the app client:
8. App client name: [Your App Client Name]
9. Generate client secret: Yes (recommended)
10. Auth Flows Configuration:
    • Enable ALLOW_REFRESH_TOKEN_AUTH
    • Enable ALLOW_USER_PASSWORD_AUTH
    • Enable ALLOW_USER_SRP_AUTH
11. Click Create app client
12. In the App Integration tab, find the Hosted UI section and click Edit
13. Configure the Hosted UI:
    • Callback URL(s): https://your-genesis-domain.com
    • Sign out URL(s): https://your-genesis-domain.com/api/auth/callback/cognito
    • OAuth grant type: Select both Authorization code grant and Implicit grant
    • OpenID Connect Scopes: Select openid, email, phone, and profile
14. Click Save changes
15. Note the following values for environment configuration:
    • User Pool ID (from the user pool's General settings)
    • App client ID (from the App clients section)
    • App client secret (from the App clients section)

Cognito Button

Juno internally uses AWS Cognito, so the Cognito login button will display the Juno logo in the authentication interface.

Basic authentication

We also provide a basic authentication setup, which does not require you to have any enterprise authentication available. It is built for local development & testing of the Juno.

It is intended for local testing and insecure by design. It's not appropriate for production use.

To use it:

1. Set the BASIC_AUTH_EMAIL and BASIC_AUTH_PASSWORD environment variables, as in the example below.
2. Make sure the owner user email you configure in Juno-Bootstrap matches BASIC_AUTH_EMAIL.

That's it! Once you deploy, you will be able to sign-in with the credentials you provided.

AD/LDAP Authentication (Early Access)

AD/LDAP authentication is available for early access users. To set up LDAP authentication, follow these steps:

1. Ensure you have access to an LDAP server (e.g., Microsoft Active Directory)
2. Configure your LDAP server with the necessary user directory and permissions
3. You must provide a bind user DN and password - a bind user is a standard account able to authenticate against your directory and query user attributes. We recommend it to be a specific service account used only for Juno, with no extra privileges

When using Active Directory, we also support LDAPs.

You can pass in the connection string (LDAP_URI) in the format of: ldaps://my-server:<port> eg. ldaps://dc1.ad.example.com:689 When using your own Certificate Authority you can optionally pass it in, to enable self-signed CAs.

For this to work, take your CA cert in the PEM format and then base64 encode it:

cat ca_cert.pem | base64 -w0

You can pass the resulting string to the option outlined below.

Environment Configuration

After setting up your authentication provider, update your Juno Cluster Bootstrap configuration file with the appropriate environment variables. The configuration should be added to the env section as shown below:

# Juno Cluster Bootstrap configuration
config:
  # Other configuration settings...

  # Environment Variables
  env:   
    # You must have either Google or AWS Cognito configured.
    # Uncomment one of the following (REQUIRED)
    ### Google OAuth (Uncomment if using)
    # GOOGLE_CLIENT_ID: "your-google-client-id"
    # GOOGLE_CLIENT_SECRET: "your-google-client-secret"
    ### AWS Cognito (Uncomment if using)
    # COGNITO_CLIENT_ID: "your-cognito-app-client-id"
    # COGNITO_CLIENT_SECRET: "your-cognito-app-client-secret"
    # COGNITO_ISSUER: "https://cognito-idp.{region}.amazonaws.com/{userPoolId}"
    ### LDAP (Uncomment if using)
    #  The CA cert is optional.
    #  It is to support LDAPS certs signed with your own CA.
    #  It expects a PAM-formatted CA cert exported as base64 string.
    # LDAP_URI: "ldap://your-ldap-server:389"
    # LDAP_BIND_DN: "cn=admin,dc=example,dc=com"
    # LDAP_BIND_PASSWORD: "password"
    # LDAP_SEARCH_BASE: "dc=example,dc=com"
    # LDAP_EMAIL_ATTRIBUTE: "mail"
    # LDAP_USERNAME_ATTRIBUTE: "samaccountname"
    # LDAPS_CA_CERT_BASE64:
    #   This is the option we provide for local development.
    #   It is insecure and not recommended for production use.
    # BASIC_AUTH_EMAIL: "your-email@example.com"
    # BASIC_AUTH_PASSWORD: "your-password"
    # BASIC_AUTH_EMAIL_2: "another-email@example.com"
    # BASIC_AUTH_PASSWORD_2: "another-password"

Troubleshooting

Common Issues

Problem	Possible Solution
"Redirect URI Mismatch" error	Ensure the redirect URI in your provider configuration exactly matches your application's callback URL
Authentication timeout	Check network connectivity between your application and the authentication provider
"Invalid Client" error	Verify that your client ID and secret are correct and properly configured
Users cannot log in	Ensure the user has been added to the user directory and has the correct permissions

Security Best Practices

To maintain a secure authentication system:

1. Never use basic authentication in production
2. Use HTTPS for all authentication endpoints and redirects
3. Monitor authentication logs for suspicious activity

For further assistance, contact Juno Support.