Skip to main content

​
Overview

Application models represent OAuth2/OIDC applications, API applications, and SAML applications in Zitadel. These models define the configuration for different application types.

​
ApplicationServiceApplication

The main application model that can represent OIDC, API, or SAML applications.
​
application_id
string
Unique identifier of the application
​
creation_date
Time
Timestamp when the application was created
​
change_date
Time
Timestamp when the application was last modified
​
state
ApplicationServiceApplicationState
Current state of the application (e.g., ACTIVE, INACTIVE)
​
name
string
Name of the application that can be displayed to users
​
project_id
string
ID of the project the application belongs to
​
api_configuration
ApplicationServiceAPIConfiguration
Configuration for API applications. Present only for API type applications
​
oidc_configuration
ApplicationServiceOIDCConfiguration
Configuration for OIDC/OAuth2 applications. Present only for OIDC type applications
​
saml_configuration
ApplicationServiceSAMLConfiguration
Configuration for SAML applications. Present only for SAML type applications

​
Example JSON

{
  "applicationId": "456789123",
  "creationDate": "2024-01-15T10:30:00Z",
  "changeDate": "2024-03-01T14:20:00Z",
  "state": "APPLICATION_STATE_ACTIVE",
  "name": "My Web Application",
  "projectId": "123456789",
  "oidcConfiguration": {
    "clientId": "client_abc123",
    "redirectUris": ["https://app.example.com/callback"],
    "responseTypes": ["OIDC_RESPONSE_TYPE_CODE"],
    "grantTypes": ["OIDC_GRANT_TYPE_AUTHORIZATION_CODE"],
    "applicationType": "OIDC_APPLICATION_TYPE_WEB",
    "authMethodType": "OIDC_AUTH_METHOD_TYPE_BASIC"
  }
}

​
Example Usage

application = response.application

puts "Application: #{application.name}"
puts "ID: #{application.application_id}"
puts "Project: #{application.project_id}"
puts "Created: #{application.creation_date.strftime('%Y-%m-%d')}"

# Check application type and access configuration
if application.oidc_configuration
  puts "OIDC Application"
  puts "Client ID: #{application.oidc_configuration.client_id}"
elsif application.api_configuration
  puts "API Application"
  puts "Client ID: #{application.api_configuration.client_id}"
elsif application.saml_configuration
  puts "SAML Application"
end

​
ApplicationServiceOIDCConfiguration

Configuration for OIDC/OAuth2 applications.
​
redirect_uris
array<string>
Allowed callback URIs for OAuth2/OIDC flows where the authorization code or tokens will be sent
​
response_types
array<ApplicationServiceOIDCResponseType>
Define whether a code, id_token token or just id_token will be returned
​
grant_types
array<ApplicationServiceOIDCGrantType>
Define the flow type the application is allowed to use
​
application_type
ApplicationServiceOIDCApplicationType
Type of OIDC application (WEB, USER_AGENT, NATIVE)
​
client_id
string
Unique OAuth2/OIDC client_id used for authentication
​
auth_method_type
ApplicationServiceOIDCAuthMethodType
Authentication method type (BASIC, POST, NONE, PRIVATE_KEY_JWT)
​
post_logout_redirect_uris
array<string>
Allowed URIs to redirect to after logout
​
version
ApplicationServiceOIDCVersion
OIDC version (1.0)
​
non_compliant
boolean
Whether the config is OIDC compliant. Non-compliant configurations may have interoperability issues
​
compliance_problems
array<ApplicationServiceOIDCLocalizedMessage>
List of compliance problems for non-compliant configurations
​
development_mode
boolean
Allows OIDC non-compliant settings for development (HTTP redirect URIs, wildcards)
​
access_token_type
ApplicationServiceOIDCTokenType
Type of access token (JWT or Bearer)
​
access_token_role_assertion
boolean
Whether user roles are added to the access token
​
id_token_role_assertion
boolean
Whether user roles are added to the id token
​
id_token_userinfo_assertion
boolean
Whether profile, email, address, and phone claims are added to id token even when access token is issued
​
clock_skew
string
Allowed clock skew duration for token validation
​
additional_origins
array<string>
HTTP origins from where the API can be used additional to redirect_uris
​
allowed_origins
array<string>
All HTTP origins where the application is allowed to be used from (generated from redirect_uris and additional_origins)
​
skip_native_app_success_page
boolean
Skip success page and open application directly for native apps
​
back_channel_logout_uri
string
URI for OIDC Back-Channel Logout notifications
​
login_version
ApplicationServiceLoginVersion
Version of the login UI to use

​
Example Usage

oidc_config = application.oidc_configuration

if oidc_config
  puts "Client ID: #{oidc_config.client_id}"
  puts "Application Type: #{oidc_config.application_type}"
  puts "Auth Method: #{oidc_config.auth_method_type}"
  
  puts "\nRedirect URIs:"
  oidc_config.redirect_uris.each do |uri|
    puts "  - #{uri}"
  end
  
  puts "\nGrant Types:"
  oidc_config.grant_types.each do |grant|
    puts "  - #{grant}"
  end
  
  puts "\nToken Settings:"
  puts "  Access Token Type: #{oidc_config.access_token_type}"
  puts "  Role Assertion: #{oidc_config.access_token_role_assertion}"
  puts "  Development Mode: #{oidc_config.development_mode}"
  
  if oidc_config.non_compliant
    puts "\nCompliance Issues:"
    oidc_config.compliance_problems.each do |problem|
      puts "  - #{problem.message}"
    end
  end
end

​
ApplicationServiceAPIConfiguration

Configuration for API applications.
​
client_id
string
Unique OAuth2 client_id used for authentication at the introspection endpoint
​
auth_method_type
ApplicationServiceAPIAuthMethodType
Authentication method type (BASIC, PRIVATE_KEY_JWT)

​
Example JSON

{
  "clientId": "api_client_xyz789",
  "authMethodType": "API_AUTH_METHOD_TYPE_PRIVATE_KEY_JWT"
}

​
Example Usage

api_config = application.api_configuration

if api_config
  puts "API Application"
  puts "Client ID: #{api_config.client_id}"
  puts "Auth Method: #{api_config.auth_method_type}"
  
  if api_config.auth_method_type == 'API_AUTH_METHOD_TYPE_PRIVATE_KEY_JWT'
    puts "Uses private key JWT authentication"
  elsif api_config.auth_method_type == 'API_AUTH_METHOD_TYPE_BASIC'
    puts "Uses basic authentication"
  end
end

​
Working with Applications

​
Determining Application Type

def get_application_type(application)
  return :oidc if application.oidc_configuration
  return :api if application.api_configuration
  return :saml if application.saml_configuration
  :unknown
end

app_type = get_application_type(application)
puts "Application type: #{app_type}"

​
Validating OIDC Configuration

def validate_oidc_config(oidc_config)
  errors = []
  
  errors << "No redirect URIs configured" if oidc_config.redirect_uris.empty?
  errors << "No grant types configured" if oidc_config.grant_types.empty?
  
  if oidc_config.non_compliant
    errors << "Application is not OIDC compliant"
    oidc_config.compliance_problems.each do |problem|
      errors << "  - #{problem.message}"
    end
  end
  
  if oidc_config.development_mode && !is_development_environment?
    errors << "Development mode should not be enabled in production"
  end
  
  errors
end

errors = validate_oidc_config(application.oidc_configuration)
if errors.any?
  puts "Configuration issues:"
  errors.each { |err| puts "  - #{err}" }
else
  puts "Configuration is valid"
end

​
Checking Redirect URI

def redirect_uri_allowed?(application, uri)
  return false unless application.oidc_configuration
  
  application.oidc_configuration.redirect_uris.include?(uri)
end

callback_uri = "https://app.example.com/callback"
if redirect_uri_allowed?(application, callback_uri)
  puts "Redirect URI is allowed"
else
  puts "Redirect URI is not configured"
end

​
Managing CORS Origins

def get_all_allowed_origins(application)
  return [] unless application.oidc_configuration
  
  config = application.oidc_configuration
  
  # allowed_origins is auto-generated from redirect_uris + additional_origins
  config.allowed_origins || []
end

origins = get_all_allowed_origins(application)
puts "Allowed origins:"
origins.each { |origin| puts "  - #{origin}" }

​
Application Security Settings

def get_security_settings(application)
  return nil unless application.oidc_configuration
  
  config = application.oidc_configuration
  
  {
    auth_method: config.auth_method_type,
    token_type: config.access_token_type,
    role_assertions: {
      access_token: config.access_token_role_assertion,
      id_token: config.id_token_role_assertion
    },
    development_mode: config.development_mode,
    compliant: !config.non_compliant,
    back_channel_logout: config.back_channel_logout_uri.present?
  }
end

settings = get_security_settings(application)
if settings
  puts "Security Settings:"
  puts "  Auth Method: #{settings[:auth_method]}"
  puts "  Token Type: #{settings[:token_type]}"
  puts "  Development Mode: #{settings[:development_mode]}"
  puts "  OIDC Compliant: #{settings[:compliant]}"
end

​
Common Application Patterns

​
SPA Configuration Check

def valid_spa_config?(application)
  return false unless application.oidc_configuration
  
  config = application.oidc_configuration
  
  # SPA should be USER_AGENT type
  return false unless config.application_type == 'OIDC_APPLICATION_TYPE_USER_AGENT'
  
  # Should use PKCE (implicit in auth code flow)
  return false unless config.grant_types.include?('OIDC_GRANT_TYPE_AUTHORIZATION_CODE')
  
  # Should use CODE response type
  return false unless config.response_types.include?('OIDC_RESPONSE_TYPE_CODE')
  
  true
end

if valid_spa_config?(application)
  puts "Valid SPA configuration"
else
  puts "SPA configuration needs adjustment"
end

​
Native App Configuration Check

def valid_native_app_config?(application)
  return false unless application.oidc_configuration
  
  config = application.oidc_configuration
  
  # Native app type
  return false unless config.application_type == 'OIDC_APPLICATION_TYPE_NATIVE'
  
  # Check for custom scheme redirect URIs
  has_custom_scheme = config.redirect_uris.any? { |uri| !uri.start_with?('http') }
  
  has_custom_scheme
end

if valid_native_app_config?(application)
  puts "Valid native app configuration"
else
  puts "Native app configuration needs custom scheme redirect URIs"
end
These models are used in conjunction with application models:
  • ApplicationServiceApplicationState - Enum for application states
  • ApplicationServiceOIDCResponseType - Enum for OIDC response types
  • ApplicationServiceOIDCGrantType - Enum for OAuth2 grant types
  • ApplicationServiceOIDCApplicationType - Enum for OIDC application types
  • ApplicationServiceOIDCAuthMethodType - Enum for authentication methods
  • ApplicationServiceOIDCTokenType - Enum for access token types
  • ApplicationServiceAPIAuthMethodType - Enum for API auth methods
  • ApplicationServiceSAMLConfiguration - SAML application configuration

​
Next Steps

Build docs developers (and LLMs) love

Get started for freeTalk to us