Identity Integration

This guide walks you through connecting your identity provider (IdP) to Alien Giraffe. We’ll cover the three most common providers—Okta, Azure AD, and Google Workspace—then show you how to configure user and team synchronization.

Why Integrate an Identity Provider?

Instead of creating and managing users manually in Alien Giraffe, integrate with your existing identity provider to:

• Single Sign-On (SSO): Users authenticate with their existing company credentials
• Automatic User Provisioning: New employees get access automatically
• Team Synchronization: Teams and groups stay in sync with your org structure
• Lifecycle Management: Access is revoked automatically when employees leave
• Centralized Management: One place to manage all identities

Before You Begin

Make sure you have:

• Administrator access to your identity provider
• Alien Giraffe installed and running (Installation Guide)
• Your Alien Giraffe public URL (e.g., https://a10e.company.com)

Quick Start: Okta

Okta is a popular cloud-based identity provider. Here’s how to integrate it.

Step 1: Create Okta Application

1. Log into your Okta admin console

2. Navigate to Applications → Applications → Create App Integration

3. Select OIDC - OpenID Connect

4. Select Web Application

5. Configure the application:

   • App integration name: Alien Giraffe
   • Grant type: Authorization Code
   • Sign-in redirect URIs: https://a10e.company.com/auth/callback
   • Sign-out redirect URIs: https://a10e.company.com/auth/logout
   • Assignments: Select who should have access

6. Click Save and note:

   • Client ID: 0oa...
   • Client Secret: (click to reveal)

Step 2: Configure Group Claims

To sync teams from Okta groups:

1. In your Okta application, go to Sign On tab
2. Scroll to OpenID Connect ID Token
3. Click Edit
4. Add a Groups claim:
   • Claim name: groups
   • Value type: Filter
   • Filter: Matches regex: .* (or specify pattern like a10e-.*)

Step 3: Create Integration in Alien Giraffe

Create identity/okta.yaml:

apiVersion: v1
kind: IdentityProvider
metadata:
  name: okta
  namespace: production

spec:
  type: oidc
  provider: okta

  config:
    issuer: https://your-domain.okta.com
    clientId: 0oa...
    clientSecretRef: okta-client-secret
    scopes:
      - openid
      - profile
      - email
      - groups

  attributeMapping:
    - claim: email
      target: user.email
      required: true

    - claim: given_name
      target: user.firstName

    - claim: family_name
      target: user.lastName

    - claim: groups
      target: user.teams
      transform: lowercase

  groupSync:
    enabled: true
    filter: "a10e-*"              # Only sync groups starting with a10e-
    schedule: "*/15 * * * *"      # Every 15 minutes

Step 4: Create Client Secret

# Create secret for Okta client credentials
cat > okta-secret.yaml <<EOF
apiVersion: v1
kind: Secret
metadata:
  name: okta-client-secret
type: credentials
data:
  clientId: 0oa...
  clientSecret: your-client-secret-here
EOF

# Apply the secret
a10e secret apply -f okta-secret.yaml

Step 5: Apply Configuration

# Apply the identity provider configuration
a10e identity-provider apply -f identity/okta.yaml

# Verify it was created
a10e identity-provider list

# Test authentication
a10e identity-provider test okta

Step 6: Test Login

# Test SSO login flow
a10e auth login --provider okta

# This will:
# 1. Open browser to Okta login page
# 2. Redirect back after authentication
# 3. Create session in Alien Giraffe

# Verify your identity
a10e auth whoami

Quick Start: Azure AD (Entra ID)

Microsoft’s Azure Active Directory is common in enterprise environments.

Step 1: Register Application in Azure

1. Log into Azure Portal

2. Navigate to Azure Active Directory → App registrations → New registration

3. Configure:

   • Name: Alien Giraffe
   • Supported account types: Accounts in this organizational directory only
   • Redirect URI:
     • Type: Web
     • URI: https://a10e.company.com/auth/callback

4. Click Register and note the Application (client) ID

Step 2: Create Client Secret

1. In your app registration, go to Certificates & secrets
2. Click New client secret
3. Add description: Alien Giraffe Client Secret
4. Choose expiration (recommend 24 months)
5. Click Add and copy the secret value immediately (you can’t view it again)

Step 3: Configure API Permissions

1. Go to API permissions

2. Click Add a permission → Microsoft Graph → Delegated permissions

3. Add permissions:

   • User.Read
   • email
   • openid
   • profile
   • GroupMember.Read.All (for group sync)

4. Click Grant admin consent

Step 4: Configure Group Claims

1. Go to Token configuration
2. Click Add groups claim
3. Select Security groups
4. Choose ID and access tokens

Step 5: Create Integration in Alien Giraffe

Create identity/azure-ad.yaml:

apiVersion: v1
kind: IdentityProvider
metadata:
  name: azure-ad
  namespace: production

spec:
  type: oidc
  provider: azure-ad

  config:
    issuer: https://login.microsoftonline.com/{tenant-id}/v2.0
    clientId: your-application-id
    clientSecretRef: azure-ad-secret
    scopes:
      - openid
      - profile
      - email
      - User.Read

  attributeMapping:
    - claim: email
      target: user.email
      required: true

    - claim: given_name
      target: user.firstName

    - claim: family_name
      target: user.lastName

    - claim: groups
      target: user.teams

  groupMapping:
    # Map Azure AD group object IDs to team names
    - azureGroupId: "a1b2c3d4-..."
      team: engineering

    - azureGroupId: "e5f6g7h8-..."
      team: data-science

  groupSync:
    enabled: true
    schedule: "0 * * * *"         # Hourly

Step 6: Apply Configuration

# Create secret
cat > azure-ad-secret.yaml <<EOF
apiVersion: v1
kind: Secret
metadata:
  name: azure-ad-secret
type: credentials
data:
  clientId: your-application-id
  clientSecret: your-client-secret
  tenantId: your-tenant-id
EOF

a10e secret apply -f azure-ad-secret.yaml

# Apply identity provider
a10e identity-provider apply -f identity/azure-ad.yaml

# Test
a10e identity-provider test azure-ad

Quick Start: Google Workspace

Google Workspace (formerly G Suite) integration for Google-based organizations.

Step 1: Create OAuth Client

1. Go to Google Cloud Console

2. Create a new project or select existing

3. Navigate to APIs & Services → Credentials

4. Click Create Credentials → OAuth client ID

5. Configure:

   • Application type: Web application
   • Name: Alien Giraffe
   • Authorized redirect URIs: https://a10e.company.com/auth/callback

6. Click Create and note:

   • Client ID
   • Client Secret

Step 2: Enable Required APIs

1. Navigate to APIs & Services → Library
2. Enable these APIs:
   • Google+ API (for user info)
   • Admin SDK API (for group sync)

Step 3: Configure Domain-Wide Delegation (for Group Sync)

1. Navigate to IAM & Admin → Service Accounts
2. Create service account: alien-giraffe-sync
3. Grant role: Project → Viewer
4. Create and download JSON key
5. In Google Workspace Admin:
   • Go to Security → API Controls → Domain-wide Delegation
   • Add client ID with scopes:
     • https://www.googleapis.com/auth/admin.directory.group.readonly

Step 4: Create Integration in Alien Giraffe

Create identity/google-workspace.yaml:

apiVersion: v1
kind: IdentityProvider
metadata:
  name: google-workspace
  namespace: production

spec:
  type: oidc
  provider: google

  config:
    hostedDomain: company.com     # Restrict to your domain
    clientId: your-client-id.apps.googleusercontent.com
    clientSecretRef: google-oauth-secret
    scopes:
      - openid
      - email
      - profile

  attributeMapping:
    - claim: email
      target: user.email
      required: true
      validate: ".*@company\\.com$"  # Ensure company domain

    - claim: given_name
      target: user.firstName

    - claim: family_name
      target: user.lastName

    - claim: hd                    # Hosted domain
      target: user.domain

  groupSync:
    enabled: true
    apiCredentialsRef: google-service-account
    schedule: "0 * * * *"          # Hourly

Step 5: Apply Configuration

# Create OAuth secret
cat > google-oauth-secret.yaml <<EOF
apiVersion: v1
kind: Secret
metadata:
  name: google-oauth-secret
type: credentials
data:
  clientId: your-client-id.apps.googleusercontent.com
  clientSecret: your-client-secret
EOF

# Create service account secret (for group sync)
cat > google-service-account.yaml <<EOF
apiVersion: v1
kind: Secret
metadata:
  name: google-service-account
type: credentials
data:
  serviceAccountJson: |
    {
      "type": "service_account",
      "project_id": "your-project",
      ...
    }
EOF

# Apply secrets and identity provider
a10e secret apply -f google-oauth-secret.yaml
a10e secret apply -f google-service-account.yaml
a10e identity-provider apply -f identity/google-workspace.yaml

# Test
a10e identity-provider test google-workspace

User and Team Synchronization

How Sync Works

When enabled, Alien Giraffe periodically:

1. Queries your IdP for users and groups
2. Maps attributes using your configuration
3. Creates/updates users in Alien Giraffe
4. Assigns teams based on group memberships
5. Deactivates users removed from IdP

Configure Sync Schedule

spec:
  groupSync:
    enabled: true
    schedule: "*/15 * * * *"      # Every 15 minutes (cron format)
    fullSyncSchedule: "0 2 * * *" # Full sync daily at 2 AM

Attribute Mapping

Map IdP attributes to Alien Giraffe user fields:

spec:
  attributeMapping:
    # Basic attributes
    - claim: email
      target: user.email
      required: true

    - claim: name
      target: user.fullName

    # Custom attributes
    - claim: department
      target: user.department

    - claim: employee_id
      target: user.employeeId

    # With transformation
    - claim: email
      target: user.username
      transform: extract-before-at  # alice@company.com → alice

    # With validation
    - claim: email
      target: user.email
      validate: ".*@(company\\.com|partner\\.com)$"

Group Mapping

Map IdP groups to Alien Giraffe teams:

Direct Mapping:

spec:
  groupMapping:
    - externalGroup: "Engineering-Team"
      team: engineering

    - externalGroup: "Data-Science"
      team: data-science

Pattern-Based Mapping:

spec:
  groupMapping:
    - pattern: "a10e-*"
      transform: remove-prefix     # a10e-engineering → engineering

    - pattern: "*-admin"
      transform: add-admin-role    # Set admin role flag

Manual Sync Trigger

# Manually trigger a sync
a10e identity-provider sync okta

# Sync specific groups
a10e identity-provider sync okta --groups engineering,data-science

# Full sync (all users and groups)
a10e identity-provider sync okta --full

# View sync status
a10e identity-provider sync-status okta

Managing Users and Teams

View Users

# List all users
a10e user list

# View user details
a10e user get alice@company.com

# See user's teams
a10e user teams alice@company.com

View Teams

# List all teams
a10e team list

# View team members
a10e team members engineering

# View team access policies
a10e team policies engineering

Manual User Creation

For users not in your IdP:

# Create a user manually
a10e user create contractor@external.com \
  --first-name John \
  --last-name Doe \
  --teams contractor \
  --role user

# Add user to team
a10e user add-team contractor@external.com data-science

Testing Authentication

Test SSO Flow

# Test login with your IdP
a10e auth login --provider okta

# Verify your session
a10e auth whoami

# Test token claims
a10e auth token --decode

Test User Lookup

# Test if a user exists
a10e user get alice@company.com

# Test team membership
a10e user has-team alice@company.com engineering

Test Policy Evaluation

# Test if a user can access a source
a10e policy test my-policy \
  --user alice@company.com \
  --source production-db \
  --explain

Troubleshooting

Authentication Failures

Problem: “Invalid client credentials”

# Verify client ID and secret
a10e secret get okta-client-secret

# Test manually with curl
curl -X POST https://your-domain.okta.com/oauth2/v1/token \
  -d "grant_type=client_credentials" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET"

Problem: “Redirect URI mismatch”

• Verify redirect URI in IdP matches exactly: https://a10e.company.com/auth/callback
• Check for HTTP vs HTTPS
• Ensure no trailing slashes

Problem: “User not found after login”

# Check attribute mapping
a10e identity-provider get okta

# View raw token claims
a10e auth login --provider okta --debug

# Check user was created
a10e user list

Group Sync Issues

Problem: “Groups not syncing”

# Check sync status
a10e identity-provider sync-status okta

# View sync logs
a10e logs --component identity-sync --since 1h

# Manually trigger sync
a10e identity-provider sync okta --full

Problem: “Permission denied to read groups”

• Verify API permissions granted (Azure AD, Google)
• Check service account has correct scopes (Google)
• Ensure admin consent granted (Azure AD)

Best Practices

Security

1. Use separate client credentials for each environment (dev, staging, prod)
2. Rotate secrets regularly (every 90-180 days)
3. Restrict group sync to only necessary groups (filter: "a10e-*")
4. Enable MFA at the IdP level for all users
5. Monitor authentication logs for suspicious activity

Reliability

1. Configure fallback authentication in case IdP is down
2. Cache user/group data to handle temporary IdP outages
3. Set appropriate sync intervals (don’t sync too frequently)
4. Monitor sync failures and alert on repeated failures

Attribute Mapping

1. Use immutable identifiers when possible (employee ID, not email)
2. Validate email domains to prevent external accounts
3. Transform claims consistently (lowercase team names)
4. Document custom mappings for future maintainers

Testing

1. Test with test users before rolling out
2. Verify group sync with test groups first
3. Monitor first week of new integrations closely
4. Have rollback plan ready

Next Steps

Now that your identity provider is integrated:

1. Create Policies - Use teams in your access policies
2. Configure Monitoring - Monitor authentication and sync
3. Systems of Record Reference - Learn advanced IdP features
4. Just-In-Time Access - Enable temporary access workflows

For provider-specific guides:

• Okta Advanced Configuration
• Azure AD Enterprise Setup
• Google Workspace Configuration
• LDAP/Active Directory