Authentication and Identity

Learn how to configure authentication methods, SSO, SAML identity providers, and authentication policies for your Aiven organization.

Aiven provides flexible authentication options for accessing your organization, from password-based login to enterprise SSO with SAML identity providers. Configure authentication policies to control how users access your resources and enforce security requirements.

Authentication methods

Users can access Aiven using multiple authentication methods:

Password

Email and password

• Traditional username/password
• Optional two-factor authentication (2FA)
• Can be disabled organization-wide

Third-Party

Social login providers

• Google
• Microsoft
• GitHub
• Can be disabled organization-wide

SAML SSO

Identity providers

• Okta, Auth0, Azure AD, Google Workspace
• FusionAuth, JumpCloud, OneLogin
• Custom SAML 2.0 providers
• Organization-managed

Tokens

API access

• Personal tokens for organization users
• Application tokens for automation
• Linked to authentication method
• Can be restricted by IP address

Authentication policies

Authentication policies control how all users in your organization can access Aiven resources. Policies are set at the organization level by organization admins.

Configuring authentication policy

1. Navigate to policy settings

   Click Admin → Authentication policy

2. Select allowed methods

   Enable or disable authentication methods for your organization

3. Configure additional settings

   Set 2FA requirements, IP restrictions, token policies

4. Save changes

   Policy takes effect immediately for all users

Changing authentication policy can immediately prevent users from accessing the organization. Test with a single user before applying organization-wide.

Password authentication

With 2FA Required

Strongest password security

When enabled:

• Users must set up 2FA to access organization resources
• Works with authenticator apps (Google Authenticator, Authy, 1Password)
• Does not affect SSO or identity provider logins
• Personal tokens continue to work

# Users enable 2FA in their profile
# Cannot be automated via CLI

Users must enable 2FA through the Aiven Console in their user profile settings.

Without 2FA

Basic password security

When enabled:

• Users log in with email and password
• 2FA is optional but recommended
• Less secure than required 2FA

Disabled

Force SSO

When disabled:

• Users cannot log in with passwords
• Must use identity provider or third-party login
• Improves security by enforcing enterprise SSO

Third-party authentication

Allow or block social login providers:

Third-party options:
  Google: Allow users to log in with Google accounts
  Microsoft: Allow users to log in with Microsoft accounts  
  GitHub: Allow users to log in with GitHub accounts

Third-party authentication is convenient but doesn’t provide the same level of control as enterprise identity providers. For production organizations, consider using SAML SSO instead.

SSO with identity providers

Control whether users can access your organization through SSO:

Any organization's IdP

Default setting

• Users who belong to multiple Aiven organizations can log in using any of those organizations’ identity providers
• More flexible for users
• Less secure for organizations

Only your organization's IdP

Recommended for most organizations

• Users must log in with one of YOUR organization’s identity providers
• Cannot use other organizations’ IdPs to access your resources
• Stronger security and control
• Recommended if you only have one Aiven organization

Personal tokens

Control whether organization users can create personal tokens:

• Enabled - Users can generate tokens for API/CLI access
• Disabled for managed users - Only non-managed users can create tokens (they still can’t use them to access your organization)
• Disabled for all - No personal tokens allowed; use application users instead

Application users and their tokens are not affected by this setting. Application tokens always work regardless of authentication policy.

Token authentication method enforcement

Ensure tokens conform to your authentication policy:

• Enabled - Tokens can only be used if they were created with an allowed authentication method
• Disabled - Tokens work regardless of how they were created

Example scenario:

1. User logs in with password, creates token
2. Authentication policy changes to only allow IdP
3. With enforcement enabled: Token stops working
4. User logs in with IdP, creates new token
5. New token works with updated policy

IP address restrictions

Limit access to trusted networks:

# Example: Only allow access from office and VPN
Allowed IP ranges:
  - 203.0.113.0/24    # Office network
  - 198.51.100.0/24   # VPN network

Applies to:

• Aiven Console access
• API calls
• CLI commands
• Personal tokens
• Application tokens

Be careful when setting IP restrictions. You can lock yourself out if you don’t include your current IP address.

SAML identity providers

Connect your organization to enterprise identity providers for single sign-on:

Supported identity providers

Okta

Popular enterprise IdP with detailed setup guide

Azure AD

Microsoft’s identity platform with setup guide

Google Workspace

Google’s enterprise IdP with setup guide

Auth0

Flexible identity platform with setup guide

OneLogin

Cloud-based IdP with setup guide

JumpCloud

Directory platform with setup guide

FusionAuth

Customer identity platform with setup guide

Custom SAML

Any SAML 2.0 compatible identity provider

Setting up an identity provider

1. Start IdP configuration in Aiven

   Admin → Identity providers → Add identity provider

   • Choose IdP type
   • Enter name
   • Note the Metadata URL and ACS URL provided by Aiven
2. Configure SAML application in your IdP

   In your identity provider (Okta, Azure AD, etc.):

   • Create new SAML application
   • Set ACS URL (Assertion Consumer Service URL)
   • Set Entity ID / Audience
   • Configure attribute mapping (email, first name, last name)
   • Assign users to the application
3. Complete setup in Aiven

   Return to Aiven Console:

   • Enter IdP URL from your identity provider
   • Enter Entity ID from your identity provider
   • Upload IdP certificate or enter certificate content
   • Save configuration
4. Link users (if needed)

   Users with email addresses on verified domains are automatically linked.

   For other users:

   • Signup URL - New users create Aiven account linked to IdP
   • Account link URL - Existing users link their Aiven account to IdP
5. Test

   Test the SSO flow before rolling out to all users

IdP configuration example (Okta)

Aiven configuration

Identity Provider Settings:
  Name: "Okta SSO"
  Type: "SAML 2.0"
  
Aiven provides:
  Metadata URL: https://api.aiven.io/v1/sso/saml/metadata/abc123
  ACS URL: https://api.aiven.io/v1/sso/saml/acs/abc123
  
You provide:
  IdP URL: https://company.okta.com/app/abc123/sso/saml
  Entity ID: http://www.okta.com/abc123
  Certificate: (X.509 certificate from Okta)

SAML Application Settings:
  Single sign on URL: https://api.aiven.io/v1/sso/saml/acs/abc123
  Audience URI: https://api.aiven.io/v1/sso/saml/metadata/abc123
  Name ID format: EmailAddress
  
Attribute Statements:
  email: user.email
  firstName: user.firstName
  lastName: user.lastName

Domain verification for SSO

Verify your email domain to automatically link users:

1. Add domain

   Admin → Domains → Add domain → Enter “company.com”

2. Add DNS record

   Add the provided TXT record to your DNS:

   TXT _aiven-challenge.company.com "abc123def456..."
   
3. Verify

   Click Verify in Aiven Console after DNS propagates

4. Link to IdP

   Associate the verified domain with your identity provider

Benefits of verified domains:

• Users automatically linked to IdP when logging in
• No need to send signup/link URLs
• Users become managed users
• Better visibility and control

# Verify domain via CLI
avn organization domain-add \
  --organization-id <ORG_ID> \
  --domain company.com

# Get verification TXT record
avn organization domain-get \
  --organization-id <ORG_ID> \
  --domain company.com

# Verify after adding DNS record  
avn organization domain-verify \
  --organization-id <ORG_ID> \
  --domain company.com

IdP security best practices

1. Enable IdP-initiated login only if needed

   Logging in from IdP dashboard is less secure than from Aiven Console

2. Rotate certificates regularly

   Update IdP certificates before expiration

3. Require authentication policy with IdP only

   Force all users to use SSO by disabling other authentication methods

4. Use short session durations

   Configure your IdP with session timeouts appropriate for your security needs

5. Enable MFA in your IdP

   Enforce multi-factor authentication in your identity provider

6. Monitor IdP access logs

   Regularly review authentication logs in both Aiven and your IdP

Authentication tokens

Tokens provide programmatic access to the Aiven API, CLI, and Terraform Provider:

Token types

Session tokens

Automatic temporary tokens

• Created when you log in to Console or CLI
• Automatically revoked on logout
• Short-lived (hours)
• Cannot be manually created

Personal tokens

User-created tokens

• Created by organization users
• Long-lived (days to months)
• Can be restricted by IP address
• Subject to authentication policy
• Linked to authentication method used when created

Application tokens

Automation tokens

• Created for application users
• Long-lived (days to months)
• Can be restricted by IP address
• NOT subject to authentication policy
• Recommended for CI/CD and automation

Creating personal tokens

1. Navigate to profile

   Click your profile icon → Tokens

2. Generate token

   Click Generate token

   Configure:

   • Description (e.g., “Laptop CLI access”)
   • Max age (session duration)
   • Allowed IP ranges (optional but recommended)
3. Save token

   Copy the token immediately - it cannot be retrieved later

4. Use token

   # Set token as environment variable
   export AIVEN_TOKEN="your-token-here"
   
   # Use with CLI
   avn project list
   
   # Use with API
   curl -H "Authorization: Bearer $AIVEN_TOKEN" \
     https://api.aiven.io/v1/project
   

# Create token via CLI (requires existing authentication)
avn user access-token create \
  --description "CI/CD Pipeline" \
  --max-age-seconds 2592000  # 30 days

# List your tokens  
avn user access-token list

# Revoke token
avn user access-token revoke <TOKEN_PREFIX>

Token security best practices

1. Use application users for automation

   Never use personal tokens for CI/CD, Terraform, or monitoring - use application users

2. Set appropriate expiration

   • Personal tokens: 30-90 days
   • Application tokens: 90 days, rotate regularly
3. Restrict by IP address

   # Limit token to specific networks
   avn organization application-user-token-create \
     --organization-id <ORG_ID> \
     --user-id <APP_USER_ID> \
     --cidr-blocks "203.0.113.0/24"
   
4. Use environment variables

   Never hardcode tokens in code or commit them to version control

5. Rotate tokens regularly

   Revoke and regenerate tokens every 90 days

6. Audit token usage

   Review active tokens monthly and revoke unused ones

7. Secure token storage

   Use secret managers (HashiCorp Vault, AWS Secrets Manager) for token storage

Tokens provide full access to your account. Treat them like passwords. If a token is compromised, revoke it immediately.

Token authentication with authentication policies

Tokens are linked to the authentication method used when they were created:

Scenario 1: No token enforcement
- User logs in with password, creates token
- Auth policy changes to "IdP only"
- Token still works (not enforced)

Scenario 2: With token enforcement  
- User logs in with password, creates token
- Auth policy changes to "IdP only" + token enforcement
- Token stops working (password not allowed)
- User logs in with IdP, creates new token
- New token works (IdP is allowed)

Application tokens are never affected by authentication policies. They always work regardless of policy settings.

Troubleshooting

Cannot log in after authentication policy change

Cause: New policy doesn’t allow your authentication method

Solution:

1. Contact organization admin to temporarily enable your auth method
2. Log in using allowed method (e.g., IdP if password is disabled)
3. Link new authentication method to your account

SAML authentication failed

Cause: Misconfiguration in IdP or Aiven

Solution:

1. Use SAML Tracer browser extension
2. Verify ACS URL and Entity ID match between IdP and Aiven
3. Check certificate is not expired
4. Verify users are assigned to SAML app in IdP
5. Check attribute mapping (email, firstName, lastName)

Invalid relay state error

Cause: Attempting to log in from IdP dashboard (IdP-initiated login)

Solution:

1. Log in from Aiven Console instead (SP-initiated login)
2. Or enable IdP-initiated login in Aiven Console
3. Or set default relay state/start URL in IdP to Aiven Console URL

Token stopped working

Cause: Authentication policy changed with token enforcement enabled

Solution:

1. Log in with allowed authentication method
2. Create new token (will be linked to allowed method)
3. Update applications with new token

IdP password doesn't work

Cause: User account not linked to IdP

Solution:

1. Get Account Link URL from IdP settings in Aiven Console
2. Follow link and log in with existing Aiven password
3. Authenticate with IdP to complete linking
4. Check linked authentication methods in profile

Locked out of organization

Cause: IP restriction or auth policy change

Solution:

1. Contact another organization admin to adjust policy
2. If no other admins, contact Aiven support
3. Use VPN to access from allowed IP range

API reference

Create personal token

curl -X POST \
  -H "Authorization: Bearer $EXISTING_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "CLI access",
    "max_age_seconds": 2592000
  }' \
  https://api.aiven.io/v1/access_token

curl -H "Authorization: Bearer $TOKEN" \
  https://api.aiven.io/v1/organization/{org_id}/identity-provider

curl -X PUT \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "password_auth_enabled": false,
    "saml_enabled": true,
    "require_two_factor": false
  }' \
  https://api.aiven.io/v1/organization/{org_id}/authentication-policy

curl -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Terraform",
    "max_age_seconds": 7776000,
    "extend_when_used": true,
    "scopes": ["authentication:read", "billing:read"]
  }' \
  https://api.aiven.io/v1/organization/{org_id}/application-user/{user_id}/token

Next steps

Users & Permissions

Manage users and grant appropriate access

Security

Learn about Aiven’s security architecture

Organizations

Set up your organization structure

Monitoring & Logs

Monitor authentication events and audit logs