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.

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

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)
    # 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"

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.