Access Federation Parameters

JFrog Platform Administration Documentation

Content Type
Administration / Platform
ft:sourceType
Paligo

The following sections in the YAML configuration file govern access federation:

  • "inbound": The inbound parameters map service ids from a source Access service to service ids to which the receiving Access service is attached. To determine the service ID of an Artifactory service, use the Get Service ID REST API endpoint.

  • "outbound": The outbound parameters define parameters that govern the synchronization of security entities outwardly from the source service to a target service.

The format of the federation YAML file parameters is as follows with the default values.

federation:
  outbound:
    entity-types-to-sync:
    - users
    - groups
    - permissions
    - tokens
    exclude-users:
    - <username 1>
    - <username 2>
    buffer-wait-millis: 30000
    buffer-max-size: 500
    consider-stale-hours: 168
    maximum-future-time-diff-millis: 60000
    timeout-millis: 3000
    number-of-retries: 3
    max-stored-events: -1
    auto-full-sync-recovered-servers: false
 
    servers:
    - name: "<target-name>"
      url: "<target-url>"
    - name: "<target-name>"
      url: "<target-url>"
    ...
    - name: "<target-name>"
      url: "<target-url>"

  inbound:
    service-id-mapping:
    - from: <Source Artifactory | Xray | Distribution Service ID1>
      to: <Target Artifactory | Xray | Distribution Service ID1>
    - from: <Source Artifactory | Xray | Distribution Service ID2>
      to: <Target Artifactory | Xray | Distribution Service ID2>
    ...
    - from: <Source Artifactory | Xray | Distribution Service IDn>
      to: <Target Artifactory | Xray | Distribution Service IDn>
    allow-partial-entity-sync: true

Parameter

Values

entity-types-to-sync

Specifies which entities should be synchronized to the target servers configured. Possible values are:

- users

- groups

- permissions

- tokens

Implicit synchronization

To maintain consistency in the hierarchical relationship of entities between the different Access services in a circle of trust, the following rules apply to the synchronization of security entities:

  • For any group that is synchronized from a source Access service to a target, all the users in that group are also synchronized.

  • For any permission that is synchronized from a source Access service to a target all the users and groups associated with that permission are also synchronized.

LDAP, SAML, Crowd etc.

When using 3rd party authentication providers such as LDAP, SAML, and Crowd, only the Users defined in these providers can be federated, NOT configurations.

Note also that for federation to work, these users must be created AFTER logging in to Artifactory.

exclude-users

Optional

Specific users that should be excluded from synchronization

buffer-wait-millis

Optional [Default: 30000

The time (ms) between synchronization attempts.

For example: buffer-wait-millis = 3000 means that every 30 seconds the source Access service will attempt to sync with the target Access service.

buffer-max-size

Optional [Default: 500]

The maximum number of entities that can be accumulated between synchronization attempts.

For Example: buffer-max-size = 500 means that whenever 500 security entity updates have been accumulated, the source Access service will attempt to sync with the target Access.

consider-stale-hours

Optional [Default: 168 (one week)]

The length of time a receiving server can fail to respond or respond with an error before it is considered to be "stale" and unable to be synchronized with updates. Once a server is deemed to be "stale", it can only be brought back into operation using the REST API endpoint described in Updating a Stale Server.

maximum-future-time-diff-millis

Optional [Default: 60000

If an Access service is updated, and another update is subsequently synchronized over to it, the Access service will only accept the subsequent change if its timestamp is at least maximum-future-time-diff-millis later than the previous update.

For more details, please refer to Handling Synchronization Conflicts.

timeout-millis

Optional [Default: 3000]

The length of time after synchronizing an update that an Access service will wait for acknowledgment from the receiving Access service before retrying to synchronize the update. If no acknowledgment is received within this period of time, the sending server will retry synchronizing the update to the target server the number of times specified in the number-of-retries parameter.

number-of-retries

Optional [Default: 3]

The number of times an Access service will attempt to synchronize an update to a distant service until. If an acknowledgment is not received from the target server after this number of retries the synchronization is deemed to have failed.

max-stored-events

Optional [Default: -1]

The threshold number of events stored in the database.

By default, the value is -1, which means that unlimited number of events are stored

auto-full-sync-recovered-servers

Optional [Default: false]

Whether to automatically fully synchronize stale services.

servers

The logical name and URL of target Access services to which this Access service can synchronize entities

service-id-mapping

When a service such as Mission Control, Xray, or Distribution selects an Artifactory instance as its authentication provider, that service's service ID is automatically registered with the corresponding Access service.

This field maps the service IDs of services being synchronized over to this Access service. The mapping is automatically generated by Access and need not be entered manually except for a few limitations described below.

For a synchronization target, the "from" and "to" fields define the mapping of service IDs.

The from: field should specify the service type with a wildcard character. For example, for Artifactory, specify jfrt@*, f or Xray, specify jfxr@*.

The to: field should specify the specific service to which the source service (in the from: field) is being mapped.

Limitations

  1. An access service can only serve one service of each supported type, i.e., one each of Artifactory, Mission Control, Xray, and Distribution.

  2. If you remove a registered service (for example, by changing the Artifactory that is used as the authentication provider), you need to manually remove the corresponding service ID registered with Access before you can add a new service of the same type.

  3. From version 5.4, the Artifactory service ID format changed. If you need to map a service ID whose format is from below Artifactory version 5.4 to a format that is from Artifactory version 5.4 and above, or vice versa, then you have to manually write the service ID.

  4. When upgrading Artifactory, the service ID format remains that of the originally installed version. For example, if the original version of Artifactory that you installed was version 5.2, and you have upgraded through the versions to version 5.11, the service ID format of your Artifactory installation will still be that of version 5.2.

allow-partial-entity-sync

Optional [Default: false]

Whether to allow advanced conflict resolution to merge and resolve conflicted entities.

Watch your whitespace

The YAML file format is sensitive to whitespace, so you need to ensure that all required whitespace characters are in place. If the YAML format is invalid, permissions will not be synchronized successfully and you will not receive error messages.