apollo/docs/en/development/portal-how-to-implement-user-login-function.md

Apollo is a configuration management system and will provide authority management (Authorization), theoretically it is not responsible for the implementation of user login authentication function (Authentication).

So Apollo defines some SPI's for decoupling and the key to Apollo access login is to implement these SPI's.

Implementation 1: Simple authentication using Spring Security provided by Apollo

Apollo provides a simple authentication version of Http Basic using Spring Security since 0.9.0 for this situation.

Use the following steps.

1. Install 0.9.0 or above

If the previous version is 0.8.0, you need to import apolloportaldb-v080-v090.sql

Checking ApolloPortalDB, the Users table should already exist and have an initial record. The initial user name is apollo and the password is admin.

Id	Username	Password	Email	Enabled
1	apollo	$2a$10$7r20uS.BQ9uBpf3Baj3uQOZvMVvB1RN3PYoKE94gtz2.WAOuiiwXS	apollo@acme.com	1

2. Reboot the Portal

Make sure -Dapollo_profile=github,auth if it is started by IDE

3. Add users

Super Administrator can add users by opening Administrator Tools - User Management after logging into the system.

4. Change user password

After logging in, open Administrator Tools - User Management and enter the user name and password to change the user's password, we recommend changing the password of super administrator apollo at the same time.

Implementation 2: Access to LDAP

Starting from version 1.2.0, Apollo supports ldap protocol login, which can be configured as follows.

If you use helm chart deployment method, it is recommended to implement it by configuration method without modifying the image, you can refer to Enable LDAP support

1. OpenLDAP access method

1.1 Configure application-ldap.yml

After unpacking apollo-portal-x.x.x-github.zip, create application-ldap.yml in the config directory with the following reference (sample) , the relevant content needs to be adjusted according to the specific situation:

spring:
  ldap:
    base: "dc=example,dc=org"
    username: "cn=admin,dc=example,dc=org" # Configure administrator account for searching and matching users
    password: "password"
    searchFilter: "(uid={0})" # user filter, use this filter to search for users when logging in
    urls:
    - "ldap://localhost:389"

ldap:
  mapping: # Configure the ldap attribute
    objectClass: "inetOrgPerson" # ldap user objectClass configuration
    loginId: "uid" # ldap user unique id, used as the login id
    userDisplayName: "cn" # ldap user name, used as display name
    email: "mail" # ldap mailbox attribute

1.1.1 Filtering users based on memberOf

With OpenLDAP memberOf feature enabled, the filter can be configured to narrow down the users to search for.

spring:
  ldap:
    base: "dc=example,dc=org"
    username: "cn=admin,dc=example,dc=org" # Configure admin account for searching and matching users
    password: "password"
    searchFilter: "(uid={0})" # user filter, use this filter to search for users when logging in
    urls:
    - "ldap://localhost:389"

ldap:
  mapping: # Configure the ldap attribute
    objectClass: "inetOrgPerson" # ldap user objectClass configuration
    loginId: "uid" # ldap user unique id, used as the login id
    userDisplayName: "cn" # ldap user name, used as display name
    email: "mail" # ldap mailbox attribute
  filter: # Configuration filter, currently only memberOf is supported
    memberOf: "cn=ServiceDEV,ou=DEV,dc=example,dc=org|cn=WebDEV,ou=DEV,dc=example,dc=org" # Only allow users with memberOf attribute of ServiceDEV and WebDEV to access

1.1.2 Filtering users based on Group

Starting with version 1.3.0, we support filtering users based on Group, which allows you to control that only users of a specific Group can log in and use apollo.

spring:
  ldap:
    base: "dc=example,dc=org"
    username: "cn=admin,dc=example,dc=org" # Configure admin account for searching and matching users
    password: "password"
    searchFilter: "(uid={0})" # user filter, use this filter to search for users when logging in
    urls:
    - "ldap://localhost:389"

ldap:
  mapping: # Configure the ldap attribute
    objectClass: "inetOrgPerson" # ldap user objectClass configuration
    loginId: "uid" # ldap user unique id, used as login id
    rdnKey: "uid" # ldap rdn key
    userDisplayName: "cn" # ldap user name, used as display name
    email: "mail" # ldap mailbox attribute
  group: # enable group search, only users of a specific group can login to apollo after enabling
    objectClass: "posixGroup" # Configure groupClassName
    groupBase: "ou=group" # group search base
    groupSearch: "(&(cn=dev))" # group filter
    groupMembership: "memberUid" # group memberShip eg. member or memberUid

1.2 Configure startup.sh

Modify scripts/startup.sh to specify spring.profiles.active as github,ldap.

SERVICE_NAME=apollo-portal
## Adjust log dir if necessary
LOG_DIR=/opt/logs/100003173
## Adjust server port if necessary
SERVER_PORT=8070

export JAVA_OPTS="$JAVA_OPTS -Dspring.profiles.active=github,ldap"

2. Active Directory access method

2.1 Configure application-ldap.yml

After unpacking apollo-portal-x.x.x-github.zip, create application-ldap.yml in the config directory with the following reference (sample) , the relevant content needs to be adapted to the specific case:

spring:
  ldap:
    base: "dc=example,dc=com"
    username: "admin" # Configure administrator account for searching and matching users
    password: "password"
    searchFilter: "(sAMAccountName={0})" # user filter, use this filter to search for users when logging in
    urls:
    - "ldap://1.1.1.1:389"

ldap:
  mapping: # Configure the ldap attribute
    objectClass: "user" # ldap user objectClass configuration
    loginId: "sAMAccountName" # the unique id of the ldap user, used as the login id
    userDisplayName: "cn" # ldap user name, used as display name
    email: "userPrincipalName" # ldap mailbox attribute
  filter: # optional, configure filter, currently only support memberOf
    memberOf: "CN=ServiceDEV,OU=test,DC=example,DC=com|CN=WebDEV,OU=test,DC=example,DC=com" # Only allow users with memberOf attribute of ServiceDEV and WebDEV to access

2.2 Configure startup.sh

Modify scripts/startup.sh to specify spring.profiles.active as github,ldap.

SERVICE_NAME=apollo-portal
## Adjust log dir if necessary
LOG_DIR=/opt/logs/100003173
## Adjust server port if necessary
SERVER_PORT=8070

export JAVA_OPTS="$JAVA_OPTS -Dspring.profiles.active=github,ldap"

3. ApacheDS access method

3.1 Configure application-ldap.yml

After unpacking apollo-portal-x.x.x-github.zip, create application-ldap.yml in the config directory with the following reference (sample) , the relevant content needs to be adjusted according to the specific situation:

spring:
  ldap:
    base: "dc=example,dc=com"
    username: "uid=admin,ou=system" # Configure administrator account for searching and matching users
    password: "password"
    searchFilter: "(uid={0})" # user filter, use this filter to search for users when logging in
    urls:
    - "ldap://localhost:10389"

ldap:
  mapping: # Configure the ldap attribute
    objectClass: "inetOrgPerson" # ldap user objectClass configuration
    loginId: "uid" # ldap user unique id, used as the login id
    userDisplayName: "displayName" # ldap user name, used as display name
    email: "mail" # ldap mailbox attribute

3.1.1 Filtering users based on Groups

Starting with version 1.3.0, we support filtering users based on Group, which allows you to control that only users of a specific Group can log in and use apollo.

spring:
  ldap:
    base: "dc=example,dc=com"
    username: "uid=admin,ou=system" # Configure admin account for searching and matching users
    password: "password"
    searchFilter: "(uid={0})" # user filter, use this filter to search for users when logging in
    urls:
    - "ldap://localhost:10389"

ldap:
  mapping: # Configure the ldap attribute
    objectClass: "inetOrgPerson" # ldap user objectClass configuration
    loginId: "uid" # ldap user unique id, used as the login id
    rdnKey: "cn" # ldap rdn key
    userDisplayName: "displayName" # ldap user name, used as display name
    email: "mail" # ldap mailbox attribute
  group: # Configure ldap group, only users of specific group can login apollo after enabled
    objectClass: "groupOfNames" # Configure groupClassName
    groupBase: "ou=group" # group search base
    groupSearch: "(&(cn=dev))" # group filter
    groupMembership: "member" # group memberShip eg. member or memberUid

3.2 Configuring startup.sh

Modify scripts/startup.sh to specify spring.profiles.active as github,ldap.

SERVICE_NAME=apollo-portal
## Adjust log dir if necessary
LOG_DIR=/opt/logs/100003173
## Adjust server port if necessary
SERVER_PORT=8070

export JAVA_OPTS="$JAVA_OPTS -Dspring.profiles.active=github,ldap"

Implementation 3: Access to OIDC

Since version 1.8.0 OpenID Connect login is supported, this implementation requires that the OpenID Connect login service has been deployed
Before configuration, you need to prepare:

• OpenID Connect provider configuration endpoint (RFC 8414-compliant issuer-uri), which needs to be https, e.g. https://host:port/auth/realms/apollo/.well-known/openid-configuration
• Create a client in the OpenID Connect service, the signature algorithm of the idToken must be set to RS256, get the client-id and the corresponding client-secret

1. Configure application-oidc.yml

After unpacking apollo-portal-x.x.x-github.zip, create application-oidc.yml in the config directory with the following contents (sample) , the relevant content needs to be adapted to the specific case:

1.1 Minimum configuration

server:
  # Parse reverse proxy request headers
  forward-headers-strategy: framework
spring:
  security:
    oauth2:
      client:
        provider:
          # provider-name is the name of the oidc provider, any character is fine, it is required for registration configuration
          <fill-in-the-provider-name-here>:
            # must be https, issuer-uri of oidc
            # For example, if your issuer-uri is https://host:port/auth/realms/apollo/.well-known/openid-configuration, then here you only need to configure https://host:port/auth/realms/ apollo, spring boot will process it with the /.well known/openid-configuration suffix
            issuer-uri: https://host:port/auth/realms/apollo
        registration:
          # registration-name is the name of the oidc client, any character is fine, oidc login must be configured with a registration of type authorization_code
          <fill-in-the-registration-name-here>:
            # oidc login must be configured with a registration of authorization_code type
            authorization-grant-type: authorization_code
            client-authentication-method: basic
            # client-id is the client ID configured at the oidc provider, used to log in to the provider
            client-id: apollo-portal
            # The name of the provider, which should be the same as the provider name configured above
            provider: <fill-in-the-provider-name-here>
            # openid is the required scope for oidc login, you can add other custom scopes here
            scope:
              - openid
            # client-secret is the client password configured at the oidc provider, used to log in to the provider
            # From the security point of view, it is recommended to use environment variables, which should be named as follows: dot(.), crossbar(-) The naming rule for environment variables is: replace the dot (.) and the crossbar (-) in the key of the configuration item with an underscore (_), then change all letters to uppercase, spring boot will automatically process environment variables that match this rule
            # For example, spring.security.oauth2.client.registration.registration-name.client-secret -> SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_NAME_ VDISK_CLIENT_SECRET (REGISTRATION_NAME can be replaced with the name of a custom oidc client)
            client-secret: d43c91c0-xxxx-xxxx-xxxx-xxxxxxxxxxxx

1.2 Extended Configuration

• If the OpenID Connect login service supports client_credentials mode, you can also configure a registration of type client_credentials, which can be used by apollo-portal as a client to request other resources protected by oidc

• If the OpenID Connect login service supports jwt, you can also configure ${spring.security.oauth2.resourceserver.jwt.issuer-uri} to support accessing apollo-portal via jwt

  server:
  # Parse reverse proxy request headers
  forward-headers-strategy: framework
  spring:
  security:
  oauth2:
    client:
      provider:
        # provider-name is the name of the oidc provider, any character is fine, it is required for registration configuration
        <fill-in-the-provider-name-here>:
          # must be the issuer-uri of https, oidc, and jwt if it is the same as the issuer-uri of jwt, or you can set it separately
          issuer-uri: ${spring.security.oauth2.resourceserver.jwt.issuer-uri}
      registration:
        # registration-name is the name of the oidc client, any character is fine, oidc login must be configured with a registration of type authorization_code
        <fill-in-the-registration-name-here>:
          # oidc login must be configured with a registration of authorization_code type
          authorization-grant-type: authorization_code
          client-authentication-method: basic
          # client-id is the client ID configured at the oidc provider, used to log in to the provider
          client-id: apollo-portal
          # The name of the provider, which should be the same as the provider name configured above
          provider: <fill-in-the-provider-name-here>
          # openid is the required scope for oidc login, you can add other custom scopes here
          scope:
            - openid
          # client-secret is the client password configured at the oidc provider, used to log in to the provider
          # From the security point of view, it is recommended to use environment variables, which should be named as follows: dot(.), crossbar(-) The naming rule for environment variables is: replace the dot (.) and the crossbar (-) in the key of the configuration item with an underscore (_), then change all letters to uppercase, spring boot will automatically process environment variables that match this rule
          # For example, spring.security.oauth2.client.registration.registration-name.client-secret -> SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_NAME_ VDISK_CLIENT_SECRET (REGISTRATION_NAME can be replaced with the name of a custom oidc client)
          client-secret: d43c91c0-xxxx-xxxx-xxxx-xxxxxxxxxxxx
        # registration-name-client is the name of the oidc client, any character is allowed, registration of client_credentials type is optional, can not be configured
        registration-name-client:
          # registration of client_credentials type is optional, used by apollo-portal as a client to request other oidc-protected resources, may not be configured
          authorization-grant-type: client_credentials
          client-authentication-method: basic
          # client-id is the client ID configured at the oidc provider, used to log in to the provider
          client-id: apollo-portal
          # The name of the provider, which must be the same as the provider name configured above
          provider: <fill-in-the-provider-name-here>
          # openid is the required scope for oidc login, you can add other custom scopes here
          scope:
            - openid
          # client-secret is the client password configured at the oidc provider, used to log in to the provider, multiple registrations can be referenced if the password is the same
          client-secret: ${spring.security.oauth2.client.registration.registration-name.client-secret}
    resourceserver:
      jwt:
        # must be issuer-uri for https, jwt
        # For example, if your issuer-uri is https://host:port/auth/realms/apollo/.well-known/openid-configuration, then here you only need to configure https://host:port/auth/realms/ apollo, spring boot will automatically add the /.well known/openid-configuration suffix when processing
        issuer-uri: https://host:port/auth/realms/apollo
  

1.3 Configure user display name

you can also configure a custom user display name in the application-oidc.yml

• see https://openid.net/specs/openid-connect-core-1_0.html#StandardClaims for standard oidc claim name, and see your OpenID Connect service manager or ISP for nonstandard claim name.
• the configuration property name for oidc (interactive) user display name is spring.security.oidc.user-display-name-claim-name, default preferred_username, and fallback to name if the claim value of preferred_username is blank
• the configuration property name for oidc jwt user display name is spring.security.oidc.jwt-user-display-name-claim-name, has no default.

1.3.1 Example of user display name configure

• for example, using name as the claim of oidc (interactive) user display name.

  spring:
  security:
  oidc:
    user-display-name-claim-name: "name"
  
  

• for example, using email as the claim of oidc (interactive) user display name.

  spring:
  security:
  oidc:
    user-display-name-claim-name: "email"
  
  

• There is no claim name suitable for user display name in jwt standard claim name (https://tools.ietf.org/html/rfc7519#section-4), see your OpenID Connect service manager or ISP for a nonstandard claim name for display.

• for example, using user_display_name as the claim of oidc jwt user display name.

  spring:
  security:
  oidc:
    jwt-user-display-name-claim-name: "user_display_name"
  
  

• it's ok to configure oidc (interactive) user display name and oidc jwt user display name at the same time.

• for example, using name as the claim of oidc (interactive) user display name and using user_display_name as the claim of oidc jwt user display name.

  spring:
  security:
  oidc:
    user-display-name-claim-name: "name"
    jwt-user-display-name-claim-name: "user_display_name"
  
  

2. Configure startup.sh

Modify scripts/startup.sh to specify spring.profiles.active as github,oidc.

SERVICE_NAME=apollo-portal
## Adjust log dir if necessary
LOG_DIR=/opt/logs/100003173
## Adjust server port if necessary
SERVER_PORT=8070

export JAVA_OPTS="$JAVA_OPTS -Dspring.profiles.active=github,oidc"

3. Configure apollo-portal to enable https

3.1 Adding a reverse proxy header

Using nginx as an example, add or include (recommended) the following configuration directly to the http configuration section of nginx

server {
    listen 80 default_server;

    location / {
        # redirect all requests on port 80 to https
        return 301 https://$http_host$request_uri;
    }
}
server {
    # For lower versions of nginx that do not support http2, configure listen 443 ssl;
    listen 443 ssl http2;
    server_name xxx;

    # ssl certificate, nginx needs to use a full certificate chain certificate
    ssl_certificate /etc/nginx/ssl/xxx.crt;
    ssl_certificate_key /etc/nginx/ssl/xxx.key;
    # ... The rest of the ssl configuration

    location / {
        proxy_pass http://apollo-portal-dev:8070;
        proxy_set_header x-real-ip $remote_addr;
        proxy_set_header x-forwarded-for $proxy_add_x_forwarded_for;
        # !!! Here must be $http_host, if configured as $host, it will cause the port error when jumping
        proxy_set_header host $http_host;
        proxy_set_header x-forwarded-proto $scheme;
        proxy_http_version 1.1;
    }
}

3.2 Checking the application-oidc.yml configuration

The configuration item server.forward-headers-strategy=framework must exist in application-oidc.yml.

server:
  # Parse reverse proxy request headers
  forward-headers-strategy: framework

3.3 Adding a whitelist of redirects for the OpenID Connect login service

For security reasons, the OpenID Connect login service generally has a whitelist of redirected addresses, so you need to add the apollo-portal https address to the whitelist in order to redirect properly.

Implementation 4: access to the company's unified login authentication system

This approach assumes that the company already has a unified login authentication system, such as SSO and LDAP. The following SPI must be implemented to access the system, including UserService and UserInfoHolder.

The interfaces are described as follows.

• UserService (Required): User service, used to provide user search-related functions to the Portal
• UserInfoHolder (Required): Get the current login user information, SSO is generally the current login user information on ThreadLocal
• LogoutHandler (Optional): used to implement the logout function
• SsoHeartbeatHandler (Optional): If the Portal page is not refreshed for a long time, the login information will expire. Refresh the login information through this interface

You can refer to apollo-portal module's package of com.ctrip.framework.apollo.portal.spi , under this package for four implementations.

1. defaultimpl: default implementation, with only one global apollo account
2. ctrip: ctrip implementation, access to the SSO and the implementation of the user search, query interface
3. springsecurity: spring security implementation, you can add new users, modify the user password, etc.
4. ldap: ldap implementation contributed by @pandalin and codepiano

After implementing the relevant interfaces, the AuthConfiguration can be accessed via com.ctrip.framework.apollo.portal.configuration to replace the default implementation at runtime.

The idea of accessing SSO is as follows.

1. SSO will provide a jar package, you need to configure a filter
2. filter will intercept all requests and check if you are already logged in
3. if there is no login, then it will jump to the SSO login page
4. After successful login in the SSO login page, it will jump back to the apollo page with the authentication information. 5.
5. enter the SSO filter again, verify the authentication information, save the user's information, and write the user's credentials to a cookie or distributed session to avoid having to log in again next time
6. enter Apollo's code, Apollo's code will call UserInfoHolder.getUser to get the current logged-in user

Note that the above steps 1-5 are all SSO code, not Apollo code, Apollo code only requires you to implement step 6.

Note: The runtime use of different implementations is achieved by Profiles. For example, if your own sso implementation is in the custom profile, you can specify -Dapollo_profile=github,custom in the packaging script. profile. Also note that in AuthConfiguration to modify the default implementation of the condition , from @ConditionalOnMissingProfile({"ctrip", "auth", "ldap"}) to @ConditionalOnMissingProfile({"ctrip", "auth", "ldap", "custom"}).