Have a question? Want to report an issue? Contact JFrog support

Skip to end of metadata
Go to start of metadata

Overview

Access Federation gives you control over access to all, or any subset of your global JFrog Artifactory, JFrog Xray, and JFrog Distribution instances from one location by synchronizing all security entities (users, groups, permissions and access tokens) between the federated instances. Once access federation has been set up, you can manage all security entities in the federated instances from one place. This opens up previously unavailable capabilities such as:

  • providing build servers connected to any federated instance with access to any of the other Artifactory instances in the federated group
  • providing globally distributed teams, CI servers or bots with access to any Artifactory instance within a federated group 

No proxy support before Artifactory 6.1

For Artifactory versions below 6.1, an Access service that resides behind a proxy cannot be included in a circle of trust and therefore, cannot be included in access federation. 

Access federation is available from Artifactory 6.0 and requires an Enterprise+ license.

Sample Topologies

The following examples show different use cases of how Access Federation can be used.

Full Mesh Topology

Page Contents

This is a fairly simple use case that shows how security entities in a group of Artifactory clusters are fully synchronized.

Each of the Access services is configured to synchronize changes to all the others, and each Access service has been configured to trust all the others by being provided with their respective root certificates, so they are all in one all-encompassing circle-of-trust

A change made to the Access service in any of the clusters will be synchronized over to all other Access services clusters.

Mesh with DR

 

This example shows two sets of Artifactory clusters, (Full mesh access 1 and 2) federated with a Central Access server in a full mesh topology. 

In addition, the clusters and the central Access service also synchronize security entities over to an Access service serving a DR cluster.

In this configuration, should either (or both) of the Full mesh Access clusters become inoperative, the DR cluster can be activated and it will already be correctly configured with all security entities.

Once the downed cluster(s) are back in operation, you can invoke a "full broadcast" (the same one used to revive a stale service) from the DR service to bring it up-to-date with all the current security entities. At this point, you can deactivate the DR instance and you are back with your original federation configuration.


Setting Up Access Federation

Before setting up

When setting up and using Access Federation, you need to keep the following three things in mind.

Server clocks must be synchronized

If the same security entity (e.g. a user) is simultaneously updated on two (or more) federated instances of Access, the update that is registered last will overwrite the other update(s). Therefore, to ensure consistent, predictable and trackable behavior of the system as a whole, the server clocks of all the machines running a federated group of Access services must be synchronized.

Only complete entities are synchronized 

When a security entity is updated, the whole entity is synchronized to the other Access services in the federated group, not just the update. For example, if a user's password is updated, the whole "user" entity is synchronized, not just its password.

No proxy support

An Access service that resides behind a proxy cannot be included in a circle of trust and therefore, cannot be included in access federation. 

To federate a group of Access services take the following steps:

  1. Set up authentication
  2. Establish a circle of trust
  3. Configure synchronization
  4. Synchronize permission entities

Setting up Authentication

You need to set up authentication to allow Access to communicate with other Access services, and also, to allow JFrog Mission Control to communicate with Access when configuring Access federation through its UI. 

Preparing The Credentials File

The Access service requires a credentials file, bootstrap.creds,  through which you can control the Admin password and allow REST API calls to be made from different servers. 

To prepare the credentials file:

  1. Create a file called bootstrap.creds 
  2. Populate the file with the following content:

    access-admin@<ipaddress>=password

    where:
    - <ipaddress>: the IP address of the server from which you want to make REST API calls on the Access service,
    - password: the password to be used for the access-admin user

  3. Place the the bootstrap.creds file under $ARTIFACTORY_HOME/access/etc on the server where the Access service resides 
  4. You now need to assign 600 Linux permissions (Owner read & write) to the file:

     $ chmod 600 bootstrap.creds


    Exactly 600

     The permission assigned must be exactly 600. Neither a more permissive, nor a more restrictive permission setting will work

  5. Restart the Access service by restarting the corresponding Artifactory instance.

The access-admin User

Communication with an Access service by another Access service or by Mission Control is done via REST API. These REST calls need to be authenticated using the Admin user of the Access service on which you are making the call. 

In fact, there is only one user defined for an Access service; this is its Admin user and its credentials are:

User:  access-admin

Password: password

Don't confuse the Access Admin user with Artifactory Admin users

Access is a service that is separate from Artifactory. It has only one user defined, the Admin user, and is called access-admin.

Don't confuse this with any Admin user defined in Artifactory. Those can be used to make REST API calls on Artifactory. When setting up access federation, you are making REST API calls on the Access service, not on Artifactory.

Changing the Default Password

To change the default password for the access-admin user, simply follow the steps described in Preparing the Credentials File while populating the bootstrap.creds file with either of:

access-admin@localhost=<new-password>
or
access-admin@127.0.0.1=<new-password>

Establishing a Circle of Trust

An Access service will only receive updates to entities from a trusted source. To establish a "source" service as trusted, you need to copy the source service's root certificate found under $ARTIFACTORY_HOME/access/etc/keys/root.crt into the receiving service's $ARTIFACTORY_HOME/access/etc/keys/trusted folder

Rename the source service's certificate

Since an Access service may receive updates from several source services, you should rename each source service's certificate with a meaningful name. For example, if the Access service at site "us-east" should be trusted by the Access service at a site "us-west", then $ARTIFACTORY_HOME/access/etc/keys/root.crt from us-east, should be copied to $ARTIFACTORY_HOME/access/etc/keys/trusted/us-east.crt on us-west.

Configuring Synchronization

In this step, you configure which security entities an Access service should synchronize to its target services. At the same time, you may optionally set a number of parameters that govern the synchronization process. The configuration parameters are specified in a YAML configuration file that is uploaded to the different Access services.

YAML Configuration Files

There are several configuration files that may found under the $ACCESS_HOME/etc folder:

access.config.import.yml
If this file exists, it is the configuration file that the Access services actually imports when restarted. It is the values in this file that will determine the Access service configuration. If the file does not exist, Access will load access.config.template.yml.
access.config.template.yml

This is a template file provided upon installation. If includes default values for a variety of configuration parameters.

Don't modify this file

 We strongly recommend not modifying this file, so you always have the option of reverting to recommended default values

access.config.latest.yml
This file shows which configuration parameters are different from the default values in the current Access configuration.
access.config.latest.<timestamp>.yml
This file shows previous versions of the access.config.latest.yml file with a timestamp to indicate when it was replaced.

Uploading the YAML File

To setup your Access configuration files, you need to work with the above YAML files in the following way:

  • Open the access.config.template.yml file

  • Find the Key for which you would like to change the Value and copy it

  • Open the access.config.latest.yml file

  • Paste the Key - Value pair you copied and set the relevant value as desired

  • Save the access.config.latest.yml file as access.config.import.yml

  • Restart Access by restarting the corresponding Artifactory

Note that an uploaded configuration file does not update the current configuration in Access, but rather completely replaces it.

Making multiple configuration calls

You may configure synchronization as often as you want and with any combination of parameters.

Example

To change the setting of number-of-retries from 3 (the default) to 5, you would take the following steps:

  1. Open the access.config.template.yml and copy the number-of-retries: 3 Key-Value pair.
  2. Paste the copied Key-Value pair into the access.config.latest.yml file
  3. In access.config.latest.yml, change the value of number-of-retries to 5
  4. Save the modified access.config.latest.yml as access.config.import.yml 
  5. Restart Artifactory - this will restart the Access service which will then load the values in access.config.import.yml with the updated configuration

YAML File Format

The YAML file is divided into two sections:

  • "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 synchronization of security entities outwardly from the source service to a target service.

The format of the federation YAML file is shown below with 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

    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>

where:

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 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 number of milliseconds the service should wait before consecutive attempt to synchronize the configured entity types to target servers is triggered

buffer-max-size

Optional [Default: 500]

The maximum number of entities that can be updated before an attempt to synchronize the configured entity types to target servers is triggered

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 acknowledgement from the receiving Access service before retrying to synchronize the update. If no acknowledgement 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 acknowledgement is not received from the target server after this number of retries the synchronization is deemed to have failed.

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@*, for 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.

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.

Reverting to the Default Configuration

Every time you change the Access configuration by loading a new access.config.import.yml file, Access stores the current configuration, before it is replaced, in an access.config.latest.<timestamp>.yml file.

At any time, if you want to revert to the original default configuration:

  1. Find the access.config.latest.<timestamp>.yml file with the earliest timestamp. This will have been created the first time you made any changes to the Access configuration, and therefore contains the original default values.
  2. Copy the complete contents of the file and paste them into the access.config.latest.yml file
  3. Save the modified access.config.latest.yml as access.config.import.yml 
  4. Restart Artifactory - this will restart the Access service which will then load the values in access.config.import.yml with the updated configuration

Handling Synchronization Conflicts

Depending on the synchronization topology you have configured, an Access server may receive multiple updates from different sources at short time intervals Successive updates may even conflict. For example, in a full mesh topology, an Access server may have a user's password updated to one value sync'ed over from one source, but that same user's password may be updated to a different value sync'ed over from another source. To resolve such conflicts, an Access server will finalize upon the update that has the latest timestamp. However, since synchronization of server clocks may not always be completely accurate, there could still be an inconsistency when an Access server receives conflicting updates. To overcome the possible inaccuracy in synchronization of server clocks, an Access server uses a time buffer specified in the maximum-future-time-diff-millis parameter specified above. Access will not update an entity if the update arrives sooner than maximum-future-time-diff-millis milliseconds from the previous update.

Consider the following example using the default value of maximum-future-time-diff-millis = 60000.

On Access Service 1, the password for User1 is changed to "abc" at time 09:02:00:000.

However, at approximately the same time, User1 is synchronized over to Access Service 1 from Access Service 2 which has set the password to be "def".

If the change synchronized over from Access Service 2 has a timestamp that is between 09:02:00:000 and 09:02:59:999, then User1's password will be "abc" because the password synchronized from Access Service 2 is ignored.

If the change synchronized over from Access Service 2 has a timestamp that is 09:03:00:000 or later, then User1's password will be "def" because the password synchronized from Access Service 2 is deemed to be later than the one set directly on Access Server 1 so it will be accepted.


Synchronizing Data

Once your access services are configured with their corresponding YAML files, you are ready to synchronize data from the source to the target Access services.

To synchronizing data you need to manually apply the following REST API endpoint on the source service:

Description: Synchronize data from a source to a target Access service
NotesRequires Artifactory Enterprise Plus
Since
: 5.11
Security: Requires an admin user.
UsagePUT /api/v1/system/federation/[targetServer]/full_broadcast
Sample Usage:

curl -uaccess-admin:password http://localhost:8040/access/api/v1/system/federation/access-2/full_broadcast -XPUT

The access-admin user

REST API calls on an Access service need to be authenticated using the Admin user of the Access service on which you are making the call. 

In fact, there is only one user defined for an Access service; this is its Admin user and its credentials are:

User:  access-admin

Password: password

Don't confuse this with any Admin user defined in Artifactory. Those can be used to make REST API calls on Artifactory. This call is made on the Access service to revive it after a long period of inactivity, not on Artifactory.


Example

The following is an example of how you might configure a 1-way replication of permissions by synchronizing permissions settings from a source Access service in your circle of trust to a target. There are 5 steps to this process:

Obtain Service IDs

The first step is to obtain the service IDs of the Artifactory services involved in the permission synchronization relationship. Note that we need the Artifactory service IDs, although, in fact, the permissions are managed and synchronized by the corresponding Access services.

For each of the source and target Artifactory services run the the Get Service ID REST API endpoint. In this example, we are assuming you are applying this call directly on the machine that the Artifactory service is running (i.e. on localhost):

curl -uadmin:password -v http://localhost:8081/artifactory/api/system/service_id
 
On the source service, the response is:
jfrt@01c9s2y40bcs960sdxwy4302yc
 
On the target service, the response is:
jfrt@01c9wadx1fvh3d1egg7wne0e0g

Plan and map out your synchronization

We strongly recommend having the service ID of each Artifactory cluster involved ready for use, and creating a diagram that illustrates the permission synchronization topology you are implementing while assigning a logical name for service ID. In this example, we will assign the following logical names to the source and target service IDs:

access-1: jfrt@01c9s2y40bcs960sdxwy4302yc

access-2: jfrt@01c9wadx1fvh3d1egg7wne0e0g

Inbound Configuration

Load the following YAML file on the target Access service to create the service ID mapping as described in Uploading the YAML File. Note that since the target service is receiving permissions (and not synchronizing anything out), there is no need to include the entity-types-to-sync field.

federation:\n 
	inbound:\n	
		service-id-mapping:\n
			- from: jfrt@*\n
			- to: jfrt@01c9wadx1fvh3d1egg7wne0e0g\n

Don't forget to restart the Access service after placing the YAML file in the designated location.

Outbound Configuration

Outbound configuration goes on the source Access instance

Note that the Outbound configuration should be applied to the source Access instance from which you are synchronizing security entities. 

In this example, we want to synchronize all security entities using default values except for the following settings that we want to modify:

timeout-millis = 4000
number-of-retries: 5

Load the following YAML file on the source Access service as described in Uploading the YAML File to specify the above parameters and set access-2 as the synchronization target for access-1 (this example assumes the access-2 service IP address is 35.230.92.254): 

federation:\n
	outbound:\n
    	timeout-millis: 3000\n
    	number-of-retries: 3\n
	servers:\n
		name : "access-2"\n
		url : "http://35.230.92.254:8040/access"\n

Don't forget to restart the Access service after placing the YAML file in the designated location.

Invoke Synchronization

Once your federation is setup, you are ready to synchronize data by applying the Federation REST API endpoint described in Synchronizing Data on access-1:

curl -uaccess-admin:password http://localhost:8040/access/api/v1/system/federation/access-2/full_broadcast -XPUT

 


Reviving a Stale Service

A "stale" service is one that has been registered as a synchronization target, however it has not responded to any attempt to synchronize data for a period of time greater than that defined in the consider-stale-hours parameter with which the source Access service was configured. Once a target service is deemed to be stale, the source service will not may any further attempts to synchronize data to it. To "revive" a stale service and resume synchronizing data you need to manually apply the "Federation" REST API endpoint described in Synchronizing Data on the source service:


Removing a Registered Synchronization Target

To remove a synchronization target that has been registered with an Access service, you need to remove it from the YAML configuration file and reload the file as described in Uploading the YAML File.

Don't forget to restart the Access service once the file is in the designated location. 

 

 

 

  • No labels