Instance Setup and Configuration Migration

Migrating to cidaas involves more than just moving user data. You need to configure your cidaas instance to match your business requirements, user experience expectations, and security policies. This guide covers all aspects of instance configuration during migration.

Prerequisites

Before configuring your instance, complete Migration Planning to understand your user data structure and requirements.

Table of Contents

1. Hosted Pages Configuration
2. Registration Fields and Custom Fields
3. Consents Management
4. Verification Methods Configuration
5. Password Policy
6. Client Application Configuration
7. Instance Setup Checklist

Hosted Pages Configuration

Hosted pages are the login, registration, and profile pages that users interact with. Deciding between custom and default hosted pages is a critical early decision.

Decision: Custom vs Default Hosted Pages

Default Hosted Pages

cidaas provides fully functional default hosted pages that can be customized through theming and translations.

Use Default Hosted Pages When:

• You want to go live quickly
• Standard login/registration flows meet your needs
• You can achieve your brand requirements through theming
• You have limited development resources

Advantages:

• ✅ Fast implementation
• ✅ Built-in security and best practices
• ✅ Automatic updates and improvements
• ✅ Mobile-responsive by default
• ✅ Accessibility compliant

Customization Options:

• Theming - Colors, fonts, logos, layouts
• Translations - Multi-language support
• Field configuration - Show/hide fields, set requirements
• Flow customization - Progressive registration, verification flows

Custom Hosted Pages

Build your own hosted pages using cidaas APIs while maintaining full control over the user experience.

Use Custom Hosted Pages When:

• You need unique user flows not supported by defaults
• You have complex branding requirements
• You need deep integration with your application
• You have dedicated frontend development resources

Considerations:

• Requires frontend development
• You're responsible for security implementation
• Must handle all edge cases and error scenarios
• Need to maintain compatibility with cidaas API changes

Implementation:

• Use cidaas authentication APIs
• Implement OAuth2/OIDC flows
• Handle verification flows
• Manage session state

Theming Default Hosted Pages

If you choose default hosted pages, configure theming to match your brand:

Theme Configuration Steps

1. Access Theme Management

   • Navigate to Hosted Pages > Theming in admin dashboard
   • Create a new theme or modify existing

2. Configure Visual Elements

   • Logo: Upload your company logo
   • Colors: Set primary, secondary, and accent colors
   • Fonts: Choose font family and sizes
   • Background: Set background colors or images
   • Border Radius: Configure button and input styling

3. Responsive Design

   • Configure mobile, tablet, and desktop breakpoints
   • Test on different screen sizes
   • Ensure touch-friendly interactions on mobile

4. Apply Theme to Applications

   • Map theme to specific applications
   • Test theme rendering
   • Verify brand consistency

Example Theme Configuration:

:root {
  --cid-font-family: 'Inter', sans-serif;
  --cid-color-heading-desktop: #1a1a1a;
  --cid-background-color-desktop: #ffffff;
  --cid-button-border-radius-desktop: 8px;
  --cid-logo-height-desktop: 48px;
}

For detailed theming options, see the Theming Guide.

Translation, Language, and Communication Templates

Configure multi-language support for your hosted pages and communication templates (email, SMS) to ensure consistent branding and user experience across all touchpoints.

Supported Languages

cidaas supports multiple languages. Configure translations for:

• Login page
• Registration page
• Profile page
• Verification pages
• Error messages
• Email templates
• SMS templates

Translation Strategy

Decision Points:

• Which languages do you need to support?
• Do you need right-to-left (RTL) language support?
• Should language be auto-detected or user-selected?
• Do you need custom translations for specific terms?
• Which languages are needed for email and SMS communications?

Configuration Steps:

1. Enable Languages

   • Navigate to Hosted Pages > Translation Management
   • Enable required languages
   • Set default language

2. Configure Hosted Page Translations

   • Use default translations as starting point
   • Customize translations for your brand
   • Test translations with native speakers
   • Verify special characters display correctly

3. Language Detection

   • Configure browser language detection
   • Set up language selection UI
   • Handle language switching

Example Translation Configuration:

{
  "supportedLanguages": ["en", "de", "fr", "es"],
  "defaultLanguage": "en",
  "autoDetect": true,
  "customTranslations": {
    "en": {
      "login.title": "Welcome Back",
      "register.title": "Create Your Account"
    }
  }
}

For more details, see Translation and Language Management.

Communication Templates Configuration

Configure email and SMS templates to match your brand and ensure consistent messaging across all user communications.

Template Groups

cidaas organizes communication templates into Template Groups. Each application can be assigned a template group, allowing different branding for different apps or brands.

Built-in Template Groups:

• default: Pre-configured templates for common use cases (customizable)
• developer: Empty template group for custom communications

Decision:

• Use default group if single brand/app
• Create custom template groups for multiple brands or apps with different messaging

Template Types

cidaas provides default template types for common scenarios:

Template Key	Description	Communication Methods	Deactivatable
WELCOME_USER	Welcome new users	email, sms	Yes
INVITE_USER	User invitation	email, sms, ivr, push	No
RESET_PASSWORD	Password reset request	email, sms	No
VERIFY_EMAIL	Email verification	email	No
VERIFY_MOBILE	Mobile verification	sms	No
AFTER_CHANGE_PASSWORD	Password changed notification	email, sms, ivr	Yes
NEW_DEVICE	New device detected	email, sms, ivr, push	Yes
NEW_LOCATION	New location detected	email, sms, ivr, push	Yes

For complete list, see Communication Templates.

Email Template Configuration

Configuration Steps:

1. Access Template Management

   • Navigate to Communication Management > Communication Templates
   • Select template group (default or custom)
   • Choose template type (e.g., WELCOME_USER)

2. Configure Email Templates for Each Language

   • Select locale (en, de, fr, etc.)
   • Customize email subject
   • Customize email content (HTML supported)
   • Use template variables (e.g., {{given_name}}, {{email}})

3. Brand Customization

   • Add your logo
   • Set brand colors
   • Configure sender name and address
   • Design email layout and styling

Example Email Template:

Subject: Welcome to {{company_name}}, {{given_name}}!

Hello {{given_name}},

Welcome to {{company_name}}! We're excited to have you on board.

Your account has been created with:
- Email: {{email}}
- Username: {{username}}

Click here to verify your email: {{verification_link}}

Best regards,
{{company_name}} Team

Template Variables Available:

• User data: {{given_name}}, {{family_name}}, {{email}}, {{username}}
• System data: {{verification_link}}, {{reset_password_link}}, {{company_name}}
• Custom fields: {{customFields.field_name}}

SMS Template Configuration

Configuration Steps:

1. Configure SMS Templates

   • Navigate to Communication Management > Communication Templates
   • Select template type that supports SMS
   • Choose locale

2. SMS Content Considerations

   • Keep messages concise (SMS character limits)
   • Include essential information only
   • Use clear call-to-action
   • Consider URL shorteners for links

Example SMS Template:

Welcome to {{company_name}}! Verify your account: {{verification_link}}

SMS Best Practices:

• Maximum 160 characters (standard SMS)
• Use URL shorteners for links
• Include clear action items
• Consider multi-part SMS for longer messages

Multi-Language Template Configuration

Configure templates for each supported language:

Strategy:

1. Start with Default Templates

   • Use cidaas default templates as baseline
   • Available in German (de) and English (en) by default

2. Customize for Each Language

   • Translate content while maintaining brand voice
   • Adapt cultural nuances
   • Test with native speakers
   • Verify special characters render correctly

3. Template Group Assignment

   • Assign template groups to applications
   • Different apps can use different template groups
   • Allows brand-specific messaging

Example Multi-Language Template Configuration:

{
  "templateGroup": "default",
  "templateType": "WELCOME_USER",
  "templates": [
    {
      "locale": "en",
      "subject": "Welcome to {{company_name}}!",
      "content": "Hello {{given_name}}, welcome..."
    },
    {
      "locale": "de",
      "subject": "Willkommen bei {{company_name}}!",
      "content": "Hallo {{given_name}}, willkommen..."
    },
    {
      "locale": "fr",
      "subject": "Bienvenue chez {{company_name}}!",
      "content": "Bonjour {{given_name}}, bienvenue..."
    }
  ]
}

Communication Provider Configuration

Configure how emails and SMS are sent:

Email Providers:

• SYSTEM Provider: cidaas default email service
• Custom Providers: SendGrid, Mailgun, AWS SES, etc.

SMS Providers:

• SYSTEM Provider: cidaas default SMS service
• Custom Providers: Twilio, AWS SNS, etc.

Configuration Steps:

1. Set Up Communication Providers

   • Navigate to Communication Management > Communication Provider
   • Configure email provider (sender address, sender name)
   • Configure SMS provider (sender number, sender name)

2. Template Group Provider Assignment

   • Link providers to template groups
   • Different template groups can use different providers
   • Allows provider-specific configuration

Example Provider Configuration:

{
  "templateGroup": "default",
  "emailProvider": {
    "communicationMethod": "email",
    "senderAddress": "[email protected]",
    "senderName": "My Company"
  },
  "smsProvider": {
    "communicationMethod": "sms",
    "senderAddress": "+49123456789",
    "senderName": "MyCompany"
  }
}

For detailed provider setup, see Communication Provider.

Template Customization Checklist

• Identify all template types you'll use
• Create or customize template group
• Configure email templates for each language
• Configure SMS templates for each language
• Customize sender information (name, address)
• Add branding (logo, colors) to email templates
• Test templates in each language
• Verify template variables render correctly
• Test email delivery (check spam folders)
• Test SMS delivery
• Assign template groups to applications
• Configure communication providers
• Set up monitoring for delivery failures

Migration Considerations

If Migrating from Another System:

1. Extract Existing Templates

   • Export email templates from source system
   • Export SMS templates
   • Document template variables used

2. Map to cidaas Template Types

   • Match source templates to cidaas template types
   • Identify custom templates that need custom template types
   • Map template variables

3. Migrate Template Content

   • Adapt HTML structure to cidaas format
   • Update template variables to cidaas syntax
   • Test rendering in cidaas

4. Configure Providers

   • Set up same email/SMS providers if possible
   • Or migrate to new providers
   • Test delivery configuration

For comprehensive guidance, see Communication Management and Communication Templates.

Registration Fields and Custom Fields

Defining which user attributes to store in cidaas and how they're configured is crucial for your migration and ongoing operations.

Decision Framework: What to Store in cidaas

Use this framework to decide what data belongs in cidaas vs application-specific storage:

Store in cidaas When:

✅ Identity and Authentication Data

• Email, mobile number (user identifiers)
• Password hashes
• Verification status
• Authentication provider information
• MFA method configurations

✅ Profile Data Used Across Applications

• Name (given_name, family_name)
• Profile picture
• Preferred language
• Timezone
• Basic demographic data (if used by multiple apps)

✅ Data Needed in ID Token

• Any data that must be available to all applications
• Data needed for authorization decisions
• User preferences that affect authentication flows

✅ Compliance and Consent Data

• Consent records (GDPR, terms acceptance)
• Data processing preferences
• Marketing consent flags

Store in Application-Specific Storage When:

❌ Business-Specific Data

• Order history
• Shopping cart contents
• Product preferences
• Payment information
• Application-specific settings

❌ Temporary or Session Data

• Current shopping session
• Temporary preferences
• Application state

❌ Large or Complex Data Structures

• Detailed user profiles
• Historical data
• Complex nested objects

❌ Data Only Relevant to One Application

• Application-specific preferences
• Feature flags for specific apps
• App-specific user settings

Field Configuration Strategy

Step 1: Categorize Fields

Create a field inventory and categorize each field:

Field Name	Category	Store In	Required	Editable	In ID Token	Notes
email	Identity	cidaas	Yes	User	Yes	Primary identifier
given_name	Profile	cidaas	Yes	User	Yes	Used across apps
customer_id	Business	cidaas	Yes	System	Yes	Link to CRM
order_history	Business	App DB	No	System	No	Too large, app-specific
newsletter_consent	Consent	cidaas	No	User	Yes	Compliance requirement
app_preferences	App-specific	App DB	No	User	No	Only for this app

Step 2: Define Field Properties

For each field stored in cidaas, define:

Visibility:

• Visible: User can see the field
• Hidden: System-only field (e.g., internal IDs)
• Read-only: User can see but not edit

Editability:

• User-editable: User can modify in profile
• System-only: Only system/API can modify
• Admin-only: Only administrators can modify

Requirements:

• Required: Must be provided during registration
• Optional: Can be provided later
• Conditional: Required based on conditions

ID Token Inclusion:

• Always include: Field appears in ID token for all apps
• Scope-based: Include only when specific scope requested
• Never include: Field not in ID token (use UserInfo endpoint)

Step 3: Configure System Fields

cidaas provides standard system fields. Configure them based on your needs:

Required System Fields:

{
  "email": {
    "enabled": true,
    "required": true,
    "editable": true,
    "verificationRequired": true,
    "inIdToken": true
  },
  "given_name": {
    "enabled": true,
    "required": true,
    "editable": true,
    "inIdToken": true
  },
  "family_name": {
    "enabled": true,
    "required": false,
    "editable": true,
    "inIdToken": true
  }
}

Optional System Fields:

• middle_name - Middle name
• nickname - Display name
• username - Alternative identifier
• picture - Profile picture URL
• birthdate - Date of birth
• locale - User locale
• phone_number - Phone number (if not using mobile_number)

Step 4: Design Custom Fields

Create custom fields for business-specific data:

Custom Field Design Principles:

1. Keep it Simple: Prefer simple data types (string, number, boolean)
2. Avoid Nesting: Use flat structure when possible
3. Consider Size: Large data should be in application storage
4. Think About Queries: Will you need to search/filter by this field?

Example Custom Fields:

{
  "customFields": {
    "customer_id": {
      "type": "string",
      "required": true,
      "editable": false,
      "inIdToken": true,
      "description": "Link to CRM system"
    },
    "loyalty_tier": {
      "type": "string",
      "required": false,
      "editable": false,
      "inIdToken": true,
      "values": ["bronze", "silver", "gold", "platinum"]
    },
    "preferred_language": {
      "type": "string",
      "required": false,
      "editable": true,
      "inIdToken": true,
      "default": "en"
    },
    "marketing_consent": {
      "type": "boolean",
      "required": false,
      "editable": true,
      "inIdToken": false,
      "description": "GDPR marketing consent"
    }
  }
}

Configuration in cidaas:

1. Navigate to User Management > Field Settings
2. Create custom fields with appropriate data types
3. Configure field properties (required, editable, visibility)
4. Set validation rules if needed
5. Test field display in registration/profile pages

Field Configuration Examples

Example 1: E-commerce Platform

cidaas Stores:

• Identity: email, mobile_number
• Profile: given_name, family_name, birthdate
• Custom: customer_id, loyalty_tier, preferred_language
• Consent: marketing_consent, terms_accepted

Application Stores:

• Order history
• Shopping cart
• Payment methods
• Product preferences
• Wish lists

Example 2: B2B SaaS Application

cidaas Stores:

• Identity: email
• Profile: given_name, family_name, picture
• Custom: company_id, department, role, employee_id
• Consent: data_processing_consent

Application Stores:

• Workspace settings
• Project data
• Team memberships
• Feature usage data

Progressive Registration

Consider using progressive registration to improve user experience:

Benefits:

• Reduce registration friction
• Collect data over time
• Improve conversion rates

Configuration:

• Define required fields for initial registration
• Set up progressive profiling triggers
• Configure data collection prompts

See Progressive Registration for details.

Consents Management

Managing user consents (terms of service, privacy policy, marketing) is essential for compliance and user trust.

Consent Types

Identify all consents you need to manage:

Consent Type	Purpose	Required	Storage
Terms of Service	Legal agreement	Yes	cidaas
Privacy Policy	Data processing consent	Yes (GDPR)	cidaas
Marketing Consent	Email/SMS marketing	No (opt-in)	cidaas
Cookie Consent	Cookie usage	Yes (EU)	cidaas
Data Processing	GDPR requirement	Yes (EU)	cidaas
Third-party Sharing	Data sharing consent	Depends	cidaas

Consent Configuration

Step 1: Create Consent Groups

Organize consents into logical groups:

Example Consent Groups:

{
  "consentGroups": [
    {
      "name": "legal",
      "consents": [
        "terms_of_service",
        "privacy_policy"
      ],
      "required": true
    },
    {
      "name": "marketing",
      "consents": [
        "email_marketing",
        "sms_marketing",
        "newsletter"
      ],
      "required": false
    },
    {
      "name": "data_processing",
      "consents": [
        "analytics",
        "personalization",
        "third_party_sharing"
      ],
      "required": true
    }
  ]
}

Step 2: Configure Consent Requirements

Define when consents are required:

• Registration: Required during user registration
• Login: Required on first login (for existing users)
• Profile Update: Can be updated in user profile
• Periodic Review: Require re-consent after X months

Step 3: Migrate Existing Consents

If migrating from another system:

1. Extract consent data from source system
2. Map to cidaas consent structure
3. Migrate consent records with timestamps
4. Handle missing consents (re-request if required)

Example Consent Migration:

{
  "sub": "user-sub",
  "consents": [
    {
      "consentGroup": "legal",
      "consentName": "terms_of_service",
      "accepted": true,
      "acceptedAt": "2024-01-15T10:30:00Z",
      "version": "v2.1"
    },
    {
      "consentGroup": "marketing",
      "consentName": "email_marketing",
      "accepted": true,
      "acceptedAt": "2024-01-15T10:30:00Z"
    }
  ]
}

Consent Best Practices

1. Version Management: Track consent versions for legal compliance
2. Granular Control: Allow users to manage individual consents
3. Clear Language: Use plain language in consent text
4. Easy Access: Make consent management accessible in user profile
5. Audit Trail: Maintain records of consent changes

For detailed guidance, see Consent Management.

Verification Methods Configuration

Configure which verification methods users can use and how they're enrolled.

Available Verification Methods

cidaas supports multiple verification methods:

Method	Type	Use Case	Migration Considerations
Email OTP	Passwordless	Email verification	Can migrate verification status
SMS OTP	Passwordless	Mobile verification	Can migrate verification status
TOTP	MFA	Google Authenticator, etc.	May migrate secrets (if supported)
Push Notification	MFA	Mobile app push	Cannot migrate (re-enroll)
FIDO2/WebAuthn	MFA	Security keys, biometrics	Cannot migrate (re-enroll)
Pattern	MFA	Pattern/PIN	Cannot migrate (re-enroll)
Backup Codes	MFA	Recovery method	Cannot migrate (regenerate)
Magic Link	Passwordless	Email-based login	Can migrate email verification

Configuration Strategy

Step 1: Define Allowed Methods

Decide which verification methods to enable:

Decision Factors:

• User Base: Technical sophistication of users
• Security Requirements: Compliance and security needs
• User Experience: Balance security with convenience
• Cost: SMS costs, infrastructure requirements
• Migration Complexity: Which methods can be migrated

Example Configuration:

{
  "allowedMethods": {
    "email_otp": {
      "enabled": true,
      "required": false,
      "primary": false
    },
    "sms_otp": {
      "enabled": true,
      "required": false,
      "primary": false,
      "costConsideration": true
    },
    "totp": {
      "enabled": true,
      "required": false,
      "primary": true,
      "migratable": true
    },
    "push": {
      "enabled": true,
      "required": false,
      "primary": false,
      "requiresApp": true
    },
    "fido2": {
      "enabled": true,
      "required": false,
      "primary": false,
      "highSecurity": true
    }
  }
}

Step 2: Configure Method Requirements

Define when verification methods are required:

Options:

• Optional: Users can choose to enable
• Required for Registration: Must set up during registration
• Required for Login: Must use for authentication
• Conditional: Required based on risk or user type

Example Requirements:

{
  "requirements": {
    "registration": {
      "emailVerification": "required",
      "mfa": "optional"
    },
    "login": {
      "mfa": "conditional", // Based on risk score
      "backupCodes": "recommended"
    },
    "highValueOperations": {
      "mfa": "required",
      "fido2": "preferred"
    }
  }
}

Step 3: Plan Method Enrollment

Define how users will enroll in verification methods:

Enrollment Strategies:

1. During Registration

   • Prompt users to set up MFA during registration
   • Guide through setup process
   • Make it optional but recommended

2. Post-Registration Prompt

   • Prompt users after first login
   • Show benefits of MFA
   • Provide easy setup flow

3. Progressive Enrollment

   • Start with basic methods (email verification)
   • Prompt for MFA after account is established
   • Gradually introduce more secure methods

4. Mandatory Enrollment

   • Require MFA setup within X days
   • Block access until MFA is configured
   • Provide support for users having issues

Example Enrollment Flow:

Registration → Email Verification → 
First Login → MFA Setup Prompt → 
TOTP Setup → Backup Codes Generation → 
Complete

Step 4: Migration Considerations

For each verification method, plan migration approach:

Migratable Methods:

• Email verification status → Set email_verified: true
• Mobile verification status → Set mobile_number_verified: true
• TOTP secrets → Migrate if API supports (check current capabilities)

Non-Migratable Methods:

• Push notifications → Re-enroll in mobile app
• FIDO2 → Re-enroll security keys
• Backup codes → Regenerate

Migration Strategy:

1. Migrate verification status for email/mobile
2. Communicate re-enrollment requirements for MFA
3. Provide migration window for re-enrollment
4. Offer support and guidance

See Handling Verification Methods in the Migration Planning Guide for detailed strategies.

Verification Method Configuration in cidaas

1. Navigate to Verification > Methods
2. Enable desired verification methods
3. Configure method-specific settings
4. Set up enrollment flows
5. Test each method end-to-end

Password Policy

Define password requirements that balance security with user experience.

Password Policy Configuration

Policy Elements

Configure the following password policy settings:

Setting	Options	Recommendation
Minimum Length	8-64 characters	12+ for high security
Complexity Requirements	Uppercase, lowercase, numbers, special chars	Require 3 of 4
Password History	Prevent reuse of last N passwords	5-10 previous passwords
Expiration	Password expires after X days	Optional (consider alternatives)
Common Password Blocking	Block common/weak passwords	Enable
Breach Detection	Check against breach databases	Enable if available

Example Password Policy

{
  "passwordPolicy": {
    "minLength": 12,
    "requireUppercase": true,
    "requireLowercase": true,
    "requireNumbers": true,
    "requireSpecialChars": true,
    "minComplexity": 3, // Require 3 of 4 character types
    "passwordHistory": 5,
    "expirationDays": null, // No expiration
    "blockCommonPasswords": true,
    "breachDetection": true
  }
}

Migration Considerations

Password Policy During Migration:

1. Existing Passwords: Users with existing passwords may not meet new policy
2. Grace Period: Consider grace period for password updates
3. Force Reset: May need to force password reset for non-compliant passwords
4. User Communication: Inform users of policy changes

Strategy:

• Apply policy to new passwords immediately
• Allow existing passwords during migration period
• Prompt users to update passwords that don't meet policy
• Enforce policy on password changes

Alternative: Passwordless Authentication

Consider reducing reliance on passwords:

Options:

• Email-based magic links
• SMS OTP
• Push notifications
• FIDO2/WebAuthn

Benefits:

• Better user experience
• Reduced password-related support
• Improved security
• Easier migration (no password hashes)

See Passwordless Authentication for details.

Client Application Configuration

Configure each application (client) that will use cidaas for authentication, including redirect URIs, scopes, and go-live timing.

Application Inventory

Create an inventory of all applications to migrate:

Application	Type	Current Auth	Priority	Go-Live Target
Web App	Web	Legacy OAuth	High	Week 1
Mobile App iOS	Native	Legacy OAuth	High	Week 1
Mobile App Android	Native	Legacy OAuth	High	Week 1
Admin Portal	Web	Legacy SAML	Medium	Week 2
API Gateway	Backend	API Keys	Low	Week 3

Application Configuration Elements

For each application, configure:

1. Application Type

Choose the appropriate application type:

Type	Use Case	OAuth Flow
Web Application	Browser-based apps	Authorization Code + PKCE
Single Page Application (SPA)	React, Angular, Vue apps	Authorization Code + PKCE
Native Application	Mobile apps, desktop apps	Authorization Code + PKCE
Machine-to-Machine	Backend services, APIs	Client Credentials
Server Application	Traditional web apps	Authorization Code

2. Redirect URIs

Configure all valid redirect URIs for the application:

Best Practices:

• Use HTTPS for production
• Be specific (avoid wildcards when possible)
• Include all environments (dev, staging, prod)
• Consider mobile app deep links
• Include logout redirect URIs

Example Redirect URIs:

https://app.example.com/callback
https://app.example.com/auth/callback
https://staging.app.example.com/callback
myapp://callback
myapp://auth/callback

3. Scopes

Define which scopes the application needs:

Standard Scopes:

• openid - Required for OIDC
• profile - Basic profile information (name, picture)
• email - Email address
• phone - Phone number
• address - Address information
• offline_access - Refresh tokens

Custom Scopes: Create custom scopes for application-specific data:

{
  "customScopes": [
    {
      "name": "customer:read",
      "description": "Read customer information",
      "claims": ["customer_id", "loyalty_tier"]
    },
    {
      "name": "orders:read",
      "description": "Read order history",
      "claims": ["order_count", "last_order_date"]
    }
  ]
}

Scope Strategy:

• Principle of Least Privilege: Request only needed scopes
• User Consent: Some scopes may require user consent
• ID Token Size: Limit claims in ID token (use UserInfo for large data)
• Future-Proofing: Consider future needs but don't over-scope

4. Token Configuration

Configure token settings:

Access Token:

• Lifetime (typically 1 hour)
• Token type (JWT vs opaque)
• Signing algorithm

ID Token:

• Lifetime (typically short, e.g., 5 minutes)
• Claims to include
• Custom claims

Refresh Token:

• Lifetime (days, weeks, or never expires)
• Rotation policy
• Reuse detection

Example Token Configuration:

{
  "tokens": {
    "accessToken": {
      "lifetime": 3600, // 1 hour
      "type": "JWT"
    },
    "idToken": {
      "lifetime": 300, // 5 minutes
      "claims": ["sub", "email", "email_verified", "name", "picture"]
    },
    "refreshToken": {
      "lifetime": 2592000, // 30 days
      "rotation": true,
      "reuseDetection": true
    }
  }
}

5. Security Settings

Configure security features:

PKCE (Proof Key for Code Exchange):

• Required for public clients (SPA, native apps)
• Recommended for all applications
• Enhances security of authorization code flow

Client Authentication:

• Client ID + Secret (for confidential clients)
• Client ID only (for public clients)
• Certificate-based authentication (for high security)

Additional Security:

• IP restrictions (if applicable)
• CORS configuration
• Rate limiting
• Token binding

Go-Live Strategy

Plan the order and timing of application go-live:

Phased Rollout Approach

Phase 1: Low-Risk Applications (Week 1)

• Internal tools
• Low-traffic applications
• Applications with easy rollback

Phase 2: Medium-Risk Applications (Week 2-3)

• Customer-facing web applications
• Mobile applications
• Applications with moderate traffic

Phase 3: High-Risk Applications (Week 4+)

• Critical business applications
• High-traffic applications
• Applications with complex dependencies

Go-Live Checklist per Application

• Application configured in cidaas
• Redirect URIs configured and tested
• Scopes defined and tested
• Token configuration verified
• Security settings applied (PKCE, etc.)
• Integration tested in staging
• User migration completed (if applicable)
• Monitoring and alerting configured
• Rollback plan prepared
• Support team trained
• User communication prepared

Application Configuration Template

Use this template for each application:

{
  "application": {
    "name": "Web Application",
    "type": "WEB_APPLICATION",
    "clientId": "app-client-id",
    "redirectUris": [
      "https://app.example.com/callback"
    ],
    "postLogoutRedirectUris": [
      "https://app.example.com/logout"
    ],
    "scopes": [
      "openid",
      "profile",
      "email",
      "customer:read"
    ],
    "oauthFlow": "authorization_code",
    "pkceRequired": true,
    "tokenLifetime": {
      "accessToken": 3600,
      "idToken": 300,
      "refreshToken": 2592000
    },
    "goLiveDate": "2024-02-01",
    "priority": "high"
  }
}

Instance Setup Checklist

Use this comprehensive checklist to ensure all instance configuration is complete:

Hosted Pages

• Decision made: Custom vs Default hosted pages
• Theme created and configured (if using default)
• Logo and branding applied
• Colors and fonts configured
• Responsive design tested
• Languages enabled and translated
• Translation quality verified
• Hosted pages tested on all devices

Communication Templates

• Template groups created (default or custom)
• Email templates configured for each language
• SMS templates configured for each language
• Template variables tested and verified
• Email branding applied (logo, colors, layout)
• Sender information configured (name, address)
• Communication providers configured (email, SMS)
• Templates tested in all supported languages
• Email delivery tested (check spam folders)
• SMS delivery tested
• Template groups assigned to applications
• Migration of existing templates completed (if applicable)

Registration Fields

• Field inventory completed
• Decision made: What to store in cidaas vs app storage
• System fields configured (enabled, required, editable)
• Custom fields created and configured
• Field validation rules set
• Field visibility configured (visible, hidden, read-only)
• ID token claims configured
• Progressive registration configured (if used)
• Registration flow tested

Consents

• Consent types identified
• Consent groups created
• Consent text prepared and reviewed
• Consent versions managed
• Consent requirements configured
• Consent migration plan (if applicable)
• Consent management UI tested
• Legal review completed

Verification Methods

• Allowed methods determined
• Methods enabled in cidaas
• Method requirements configured
• Enrollment flow designed
• Migration strategy for each method defined
• User communication prepared (for re-enrollment)
• Each method tested end-to-end
• Backup/recovery methods configured

Password Policy

• Password policy defined
• Policy configured in cidaas
• Migration strategy for existing passwords
• User communication about policy
• Passwordless alternatives considered
• Password reset flow tested

Client Applications

• Application inventory completed
• Go-live priority assigned
• Each application configured:
  • Application type selected
  • Redirect URIs configured
  • Scopes defined
  • Token configuration set
  • Security settings applied
  • Tested in staging
• Go-live schedule created
• Monitoring configured
• Support team prepared

Testing and Validation

• End-to-end user flows tested
• All verification methods tested
• Consent flows tested
• Registration with all field types tested
• Login flows tested for all app types
• Token validation tested
• Error scenarios tested
• Mobile responsiveness verified
• Accessibility compliance verified
• Performance tested under load

Documentation and Training

• Configuration documented
• Admin team trained
• Support team trained
• User guides prepared
• API documentation updated
• Troubleshooting guides created

Next Steps

After completing instance setup:

1. Review the Migration Overview for a complete guide to user migration
2. Complete Migration Planning for user data migration strategy
3. Proceed with User Migration implementation
4. Choose your Migration Procedure (one-time, sync, or bidirectional)
5. Begin phased Application Go-Live