Create a Secure Source Manager instance to use with federated identities

This document describes how to create a Secure Source Manager instance using Workforce Identity Federation for use with an external identity provider (IdP).

For more information on Workforce Identity Federation, see Workforce Identity Federation.

For information on limitations to Workforce Identity Federation in Secure Source Manager, see Identity federation: products and limitations.

Secure Source Manager is a single-tenant service. A single Secure Source Manager instance should only include users from one Google Cloud customer unless multiple companies who have a contractual relationship need to use a single instance for collaboration.

If you are working with multiple companies and want to collaborate around source with each of them, we recommend creating a separate instance for each company.

Note: Secure Source Manager doesn't support domain-scoped projects.

Before you begin

1. Sign in to your Google Account.

   If you don't already have one, sign up for a new account.

2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

   Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

   Go to project selector

3. Enable the Secure Source Manager API.

   Enable the API

4. Install the Google Cloud CLI.

5. To initialize the gcloud CLI, run the following command:

   gcloud init

   Note: If you installed the gcloud CLI previously, make sure you have the latest version by running gcloud components update.

6. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

   Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

   Go to project selector

7. Enable the Secure Source Manager API.

   Enable the API

8. Install the Google Cloud CLI.

9. To initialize the gcloud CLI, run the following command:

   gcloud init

   Note: If you installed the gcloud CLI previously, make sure you have the latest version by running gcloud components update.
10. Install the beta Google Cloud CLI component:

    gcloud components install beta

Data encryption

By default, Google Cloud automatically encrypts data at rest using Google-owned and Google-managed encryption keys. If you have specific compliance or regulatory requirements related to the keys that protect your data, you can create Secure Source Manager instances that are encrypted with customer-managed encryption keys (CMEK).

Don't store sensitive data in instance IDs or label key-value pairs as they are not encrypted with CMEK.

If you are creating your first Secure Source Manager instance in your project, you must manually create the Secure Source Manager service agent by running the following command:

gcloud beta services identity create \
    --service=securesourcemanager.googleapis.com \
    --project=PROJECT_ID

Where PROJECT_ID is the project ID of the project where you will create your Secure Source Manager instance.

Set up Workforce Identity Federation

Before you create an instance, you must set up a Workforce Identity Federation pool and provider.

1. Create a Workforce Identity Federation pool.

   Note: the session duration for your workforce identity pool is set to one hour by default. We recommend that you set a longer duration to prevent users having to reauthenticate repeatedly during their workday.

2. Configure your workforce identity pool provider with the following attribute mappings:

   • google.subject
   • google.email

Create an instance

Before you run the command, make the following replacements:

• INSTANCE_ID: the name of the instance you want to create.
• LOCATION: the region where you want to create the instance. For information on supported locations, see Locations.
• PROJECT_ID: the project ID of the project you want to create an instance in.

Execute the following command:

curl \
    -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    https://securesourcemanager.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/instances?instance_id=INSTANCE_ID \
    -H "Content-Type: application/json" \
    -d "{workforce_identity_federation_config: {enabled: true}}"

A long-running create instance operation starts. The output looks similar to the following:

{
"name": "OPERATION_NAME",
"metadata": {
  "@type": "type.googleapis.com/google.cloud.securesourcemanager.v1.OperationMetadata",
  "createTime": "2022-11-01T14:31:32.420469714Z",
  "target": "projects/PROJECT_ID/locations/LOCATION/instances/INSTANCE_ID",
  "verb": "create",
  "requestedCancellation": false,
  "apiVersion": "v1"
},
"done": false
}

This example output includes the following values:

• OPERATION_NAME: the operation name—for example, projects/my-project/locations/us-central1/operations/operation-1234567894561-5ec69948c0f2b-60dd727f-a9b97a2e.
• PROJECT_ID: the Google Cloud project.
• LOCATION: the region where the instance is located.

Record the OPERATION_NAME as you will need to use it to check the status of the operation.

It takes up to 60 minutes to create the instance.

Check the status of the create operation

Before using any of the request data, make the following replacements:

• OPERATION_NAME: the operation name from your create command response.

HTTP method and URL:

GET https://securesourcemanager.googleapis.com/v1/OPERATION_NAME

To send your request, expand one of these options:

curl (Linux, macOS, or Cloud Shell)

Note: The following command assumes that you have logged in to the gcloud CLI with your user account by running gcloud init or gcloud auth login , or by using Cloud Shell, which automatically logs you into the gcloud CLI . You can check the currently active account by running gcloud auth list.

Execute the following command:

curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://securesourcemanager.googleapis.com/v1/OPERATION_NAME"

PowerShell (Windows)

Note: The following command assumes that you have logged in to the gcloud CLI with your user account by running gcloud init or gcloud auth login . You can check the currently active account by running gcloud auth list.

Execute the following command:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://securesourcemanager.googleapis.com/v1/OPERATION_NAME" | Select-Object -Expand Content

Once the instance is ready, the response will look similar to the following:

  "name": "projects/my-project/locations/us-central1/operations/operation-123456789012-5ec69948c0f2b-60dd727f-a9b97a2e",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.securesourcemanager.v1.OperationMetadata",
    "createTime": "2024-10-28T15:37:39.009812863Z",
    "endTime": "2024-10-28T16:10:58.416640259Z",
    "target": "projects/my-project/locations/us-central1/instances/my-instance",
    "verb": "create",
    "requestedCancellation": false,
    "apiVersion": "v1"
  },
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.cloud.securesourcemanager.v1.Instance",
    "name": "projects/my-project/locations/us-central1/instances/my-instance",
    "createTime": "2024-10-28T15:37:39.004550840Z",
    "updateTime": "2024-10-28T15:37:39.867857246Z",
    "state": "ACTIVE",
    "hostConfig": {
      "html": "my-instance-326202322590.us-central1.sourcemanager.dev",
      "api": "my-instance-326202322590-api.us-central1.sourcemanager.dev",
      "gitHttp": "my-instance-326202322590-git.us-central1.sourcemanager.dev",
      "gitSsh": "my-instance-326202322590-ssh.us-central1.sourcemanager.dev"
    },
    "workforceIdentityFederationConfig": {
      "enabled": true
    }
  }

Where the my-instance-098765432109.us-central1.sourcemanager.dev is the instance HTML URL.

it's possible for the status check to report completion before the instance is fully operational. If you encounter errors accessing the instance after creation, wait 60 minutes and try again before reaching out for assistance through Secure Source Manager Support at [e-mail].

Copy the HTML URL from the successfully created check status response. You will need this URL to access the instance though its web interface.

Access the instance

After the instance is created, you can access it through its web interface using a browser.

Note: to create repositories in the instance you need the Repo Creator role (roles/securesourcemanager.repoCreator) on the instance project and the Instance Repository Creator role (roles/securesourcemanager.instanceRepositoryCreator) on the Secure Source Manager instance.

1. To access the Secure Source Manager instance through its web interface, copy the following URL into your browser address bar.

   INSTANCE_ID-PROJECT_NUMBER.LOCATION.sourcemanager.dev

   Replace the following:

   • INSTANCE_ID with the instance name.
   • PROJECT_NUMBER with the instance's Google Cloud project number. For information on identifying projects, see Identifying projects.
   • LOCATION with the instance's region.

   An OAuth screen appears requesting your provider name.

2. Enter the name of your workforce identity provider in the following format:

   locations/global/workforcePools/POOL_ID/providers/PROVIDER_ID
   

   Replace the following:

   • POOL_ID with your Workforce Identity Federation pool ID.
   • PROVIDER_ID with your Workforce Identity Federation provider ID.

   For more information on Workforce Identity Federation pools and providers, see Manage Workforce Identity Federation identity pools and providers.

   You are prompted to sign in using your provider credentials.

3. Sign in with your provider credentials.

4. The Secure Source Manager web interface opens. You can create and view repositories and all associated issues and pull requests from the web interface.

   You must sign in again through the web interface after the session duration set in your Workforce Identity Federation pool expires.

Create your gcloud CLI login config

To authenticate with your workforce identity pool credentials to your Secure Source Manager instance using gcloud CLI commands or Git commands, you must create a login configuration with your workforce identity pool.

To create a workforce identity pool login configuration, follow the instructions in Obtain short-lived tokens for Workforce Identity Federation to create a browser-based sign-in with the gcloud CLI.

After you have authenticated, you can use Git commands to interact with your Secure Source Manager instance. To get started with Git, follow the instructions in Use Git source code management.

What's next

• Grant users instance access.
• Grant users repository access.
• Control access with IAM.