User Manual¶

The center for all operations in the Security SaaS platform is the SaaS API. You can find it at https://identity.office.sbs/saas/. The API has a Swagger open for everyone to use it easily, it can be found at https://identity.office.sbs/saas/swagger/. Below there is a list of the endpoints linked to sections of this manual:

• POST /api/instance
  • Creating an instance
  • Fill Security Database with custom configuration
• GET /api/instance/{instanceName}
  • Getting information about an instance
• PUT /api/instance/{instanceName}
  • Upgrading an instance
  • Updating settings for an instance
  • Fill Security Database with custom configuration
• DELETE /api/instance/{instanceName}
  • Deleting an instance
• POST /api/instance/{instanceName}/restart
  • Restarting an instance
• GET /api/security-version
  • Getting available Security versions
• GET /api/security-version/latest
  • Getting available Security versions
• GET /api/security-version/{version}
  • Getting available Security versions
• Housekeeping
  • Housekeeping: expired instances
  • Housekeeping: upgrade latest

Instance states¶

The above image describes all possible states an instance can be, and their transitions. If a transition has a text, then means that is an action from an API call. The rest of transitions are internal of the API service.

Creating an instance¶

Creating an instance of Security is really simple and requires a few parameters to be filled. Each instance has a unique name which is assigned when creating it, and its up to you. As you may already know, the platform does not provide any RabbitMQ server, so this must be provided at creation. There are other parameters that can be filled if needed. Below there is an explanation of the parameters:

{
  "instanceName": "string",
  "daysToExpiration": 0,
  "version": "string",
  "rabbitMq": {
    "url": "rabbitmq://sbsmpormqsmt.office.sbs/Yeah",
    "user": "string",
    "password": "string"
  },
  "securityCustomConfigurations": [
    {
      "appKey": "ORI",
      "fileName": "vanilla-wf.zip",
      "base64Data": "string"
    }
  ],
  "securityVanillaConfiguration": {
    "adminEmail": "user@example.com",
    "adminPassword": "string",
    "e2EConfig": true
  }
}

• First, the instanceName parameter. Is the name that will receive the instance (and must be unique). This name will alsob be used for the database name and the public URLs. It is recommended to use a naming convention that clearly identify who is using them (like imp29210 or wf28571). There are some requirements for the names that must be followed:

  • The name must be a DNS-compilant name (see this StackOverflow answer), that is:
    • Maximum 63 characters
    • Use only alphanumeric characters, but slashes can be used in the middle
    • Case insensitive (for that, the name must be lowercase)
    • It is recommended to use names with less than 40 characters to avoid errors after deployment

• daysToExpiration is optional, but if specified, then the instance will have an expiration date. When that day is reached, the instance will be deleted. The minimum value (if defined) is 1 day. See Housekeeping: expired instances to know more about this.

• version is also optional, but if specified, the instance will use this specficic version (see Getting available Security versions). By default uses the latest version available, and also marks the instance to be upgraded automatically when a new version is available (recommended option).

• rabbitMq options are mandatory, as mentioned before. It must have the URL to the server and virtual host rabbitMq.url, the user in rabbitMq.user and the password rabbitMq.password (which must be encrypted using Sequel.Core.Cryptography method). The API will validate the URL and password but won't check connectivity.

• securityCustomConfigurations defines custom Security configurations to deploy alongside the instance. It is not required to define configurations, but it can be useful to be able to use Security with other products. See Fill Security Database with custom configuration to know more about.

• securityVanillaConfiguration allows some customization around the Security vanilla configuration:

  • securityVanillaConfiguration.adminEmail: Defines a custom email address for the admin user. By default uses {instanceName}@example.com. Highly recommended to change that value.
  • securityVanillaConfiguration.adminPassword: Defines a custom password for the admin user. By default uses Password123!.
  • e2EConfig: If set to true, it will deploy the E2E Security configuration. It will not deploy it by default. This is not needed in most deployments.

When the request is done, and passes all validations, then the API will enqueue the request to be deployed as soon as possible. This will put the instance to enqueued. Use the GET instance endpoint to see the status of the deployment. If the deployment succeeds, it will change to ready. In case of error, it will go to errorCreating. The deployment will take some time (around 3 minutes), and while deploying, the state will be deploying.

If the deployment fails, it can be retried by sending the same request - including the instanceName, which must be the same. The output of the Ansible playbook (the "scripts" which deploys the instance) is not accessible through the API, but it is stored in database. See troubleshooting.

Below there are some examples of requests to create instances:

{
  "instanceName": "example1",
  "rabbitMq": {
    "url": "rabbitmq://rabbitmq.office.sbs/Example",
    "user": "example-user",
    "password": "EAAAAFqCRyzli+rtgXNGGv6xvxxkyh67Upr8xAR3e3SDaOFp"
  },
  "securityVanillaConfiguration": {
    "adminEmail": "email@sequel.com"
  }
}

{
  "instanceName": "example2",
  "daysToExpiration": 1,
  "rabbitMq": {
    "url": "rabbitmq://rabbitmq.office.sbs/Example",
    "user": "example-user",
    "password": "EAAAAFqCRyzli+rtgXNGGv6xvxxkyh67Upr8xAR3e3SDaOFp"
  },
  "securityVanillaConfiguration": {
    "adminEmail": "email@sequel.com"
  }
}

{
  "instanceName": "example3",
  "version": "1.47.20093.01",
  "rabbitMq": {
    "url": "rabbitmq://rabbitmq.office.sbs/Example",
    "user": "example-user",
    "password": "EAAAAFqCRyzli+rtgXNGGv6xvxxkyh67Upr8xAR3e3SDaOFp"
  },
  "securityVanillaConfiguration": {
    "adminEmail": "email@sequel.com"
  }
}

{
  "instanceName": "example3",
  "version": "1.47.20093.01",
  "rabbitMq": {
    "url": "rabbitmq://rabbitmq.office.sbs/Example",
    "user": "example-user",
    "password": "EAAAAFqCRyzli+rtgXNGGv6xvxxkyh67Upr8xAR3e3SDaOFp"
  },
  "securityCustomConfigurations": [
    {
      "appKey": "WF",
      "fileName": "wf.zip",
      "base64Data": "..."
    },
    {
      "appKey": "PB",
      "fileName": "pb.zip",
      "base64Data": "..."
    },
    {
      "appKey": "CLM",
      "fileName": "claims.zip",
      "base64Data": "..."
    }
  ],
  "securityVanillaConfiguration": {
    "adminEmail": "email@sequel.com",
    "e2EConfig": true
  }
}

Getting information about an instance¶

After the create request is completed successfully, the instance will be registered in the platform. Since that moment, the status and some information of the instance can be retrieved using the GET endpoint. If the instance is in ready state, it will show more information. Swagger has descriptions in the Schema that explains the fields. Below it there is some explainations for some options, to retrieve more information about the instance, for completness (only for ready state).

By default, when the instance is ready state, it will show a list of URLs for Security API, Authentication, Authorization and Administration, which are the public URLs.

If the option includeHealthChecks is set to true, then the response will include the contents of each health check response for the services. API, Authentication and Authorization will show the full report in json, but Administration will simply put "health". If one of the healt checks cannot be obtained, a text with the description will be put instead.

As in Security there are some logs that are still written into stdout, this endpoint allows you to read these logs easily with the option includeLogs. This will list logs for all pods (containers - services and their replicas). By default will return up to 1000 lines for each pod, but this can be reduced (or extended) with the tailLines parameter. Lines are sorted by time ascending (the last line is the more recent log entry).

Upgrading an instance¶

To upgrade an instance, call the PUT endpoint with a new version in the body and wait until upgrade. The version must be valid (see Getting available Security versions). A call to this endpoint will schedule the upgrade request to run soon and move the instance to enqueued state.

{
  "version": "1.47.20093.01"
}

{
  "version": "latest"
}

While upgrading an instance, the services could not work properly, the instance will be in upgrading state. Be patient and wait until the upgrade is finished. If the upgrade fails, it will go to errorUpgrading state. See Troubleshooting for more information. In error state, you can retry the upgrade using the same parameters.

The upgrade operation can be done with settings and/or configuration update.

Updating settings for an instance¶

To update settings, or Security configurations (or both), the same PUT endpoint can be used to do this. Currently, RabbitMQ are the only settings that can be changed. Custom configurations can be updated or added using the instructions in Fill Security Database with custom configuration section. A call to this endpoint will schedule the update request to run as soon as possible and moves the instance to enqueued state.

{
  "rabbitMq": {
    "url": "rabbitmq://newsuperrabbitmq.office.sbs/2",
    "user": "the-new-user",
    "password": "EAAAAFqCRyzli+rtgXNGGv6xvxxkyh67Upr8xAR3e3SDaOFp"
  }
}

{
  "securityCustomConfigurations": [
    {
      "appKey": "ORI",
      "fileName": "vanilla-orig.zip",
      "base64Data": "..."
    }
  ]
}

{
  "rabbitMq": {
    "url": "rabbitmq://newsuperrabbitmq.office.sbs/2",
    "user": "the-new-user",
    "password": "EAAAAFqCRyzli+rtgXNGGv6xvxxkyh67Upr8xAR3e3SDaOFp"
  },
  "securityCustomConfigurations": [
    {
      "appKey": "ORI",
      "fileName": "vanilla-orig.zip",
      "base64Data": "..."
    }
  ]
}

The instance will be in upgrading state while updating. If the update fails, it will go to errorUpgrading state. See Troubleshooting for more information. In error state, you can retry the update using the same parameters.

Fill Security Database with custom configuration¶

When creating a new instance, custom Security configuration can be uploaded in the same request and deployed alongside Security. After an instance has been created, at any time, new configuration can be uploaded to update already existing ones or add new ones. In both scenarios, the schema is the same, and all have the same limitations.

The configurations are uploaded by putting them in the same request as base64. The configuration must be stored in a zip archive with the same format as used in the sequel-security tool.

your-configuration.zip
  - Applications/
    - {appKey}/
      - Application.json
      - Authentication/
        - ApiResources.json
        - Clients.json
      - Authorization/
        - Groups.json
        - Roles.json
        - Securables.json
        - UserTypes.json
  - Users/
    - Users.json

In the create and upgrade, both have a dedication section to upload the configurations:

{
  "securityCustomConfigurations": [
    {
      "appKey": "WF",
      "fileName": "wf.zip",
      "base64Data": "..."
    },
    {
      "appKey": "PB",
      "fileName": "pb.zip",
      "base64Data": "..."
    },
    {
      "appKey": "CLM",
      "fileName": "claims.zip",
      "base64Data": "..."
    }
  ]
}

• The base64Data is where the zip in base64 must be placed for each custom configuration.
• fileName is to specify a name for the file. It is mainly for troubleshooting purposes, but it is recommended to put something understandable. The name must be unique for the request.
• appKey is the application key for the configuration. Only one application can be uploaded by zip.

cat /path/to/the/config.zip | base64 -w 0

[Convert]::ToBase64String([IO.File]::ReadAllBytes("C:\path\to\the\config.zip"))

cat /path/to/the/config.zip | base64

There are some limitations around the custom configurations:

• No TFS Tokens are accepted. __Token__ are not supported at this moment. The values must be replaced before uploading the configuration.
• The request body cannot higher than 2MiB. It is difficult to upload almost 2MiB of zips with jsons inside, but take care of not reaching the limit, upload just the necessary files.
• If the application key is invalid, it won't fail.
• When using the upgrade endpoint to update configurations, you can reuse old file names, but only if they point to an updated configuration, not for completetly different ones. To ensure no issues raise when deploying the configurations, use different file names always.

Deleting an instance¶

When an instance is not required anymore, and expiration date has not reached yet (or has no expiration date), the DELETE endpoint schedules the deletion of the instance (and moves the instance to enqueued state). This operation usually takes less than one minute to complete. When the deletion is in progress, it will change the state to deleting. If an error occurrs, it will go to state errorDeleting, and probably will be inaccessible.

Restarting an instance¶

If there have been changes in database and some of the services requires a restart (mainly Authentication or Authorization), this endpoint will restart the requested services or all if null is put in the request. This operation usually takes around 10s. The supported services are api, authentication and authorization - admin can also be restarted but it is useless because it is a static page and an nginx.

Getting available Security versions¶

The endpoints related to Security versions allow you to inspect available Security versions in the platform. The GET /api/security-version endpoint will get all available versions sorted by published date (desc - first the latest published version). The GET /api/security-version/latest endpoint will show you which version is the latest, so you will know which version is going to deploy if latest is used. And the last GET /api/security-version/{version} endpoint is useful to check if a specific version exists.

Housekeeping: expired instances¶

An instance is expired when the expiration date is reached (today is the same date as in expiration field in the GET /api/instance/{instanceName} endpoint). All those expired instances will be removed at midnight using the same method as in Deleting an instance.

Housekeeping: upgrade latest¶

All instances created with no version (or latest version) will be marked for this upgrade housekeeping task. This task will upgrade each instance marked to use always the latest version when a new version is available in the platform. You don't need to do anything.