# CSC Link specification

CSC links, sometimes known as provisioning links, contain user credentials for the application to sign in.

**Online editor** for provisioning links is available at [https://link-test.acrobits.cz/tools/cscLinks](https://link-test.acrobits.cz/tools/cscLinks).

## Format

The CSC link **MUST** be valid URI [https://datatracker.ietf.org/doc/html/rfc3986](https://datatracker.ietf.org/doc/html/rfc3986) with additional constraints:

- The scheme **MUST** be `csc` or a custom whitelabel Provisioning URI Scheme (`provisioning_uri_scheme` asset in portal asset store).
- The username (if present) **MUST** be URL-encoded exactly once.
- The password (if present) **MUST** be URL-encoded exactly once.
- The host **MUST** conform to ABNF `1*( ALPHA / DIGIT / "-" / "_" / "." ) [ "*" ]`.
- The port **MUST NOT** be specified.
- The path **MUST** be either fully omitted (i.e. no `/`) or **MUST** be `/oauth`.
- If a query is specified, parameters within **SHALL** be defined at most once, duplicates **SHALL** ignored.
- If the path is omitted, the allowed query parameters are:
  - `env` - the portal environment; it can be one of: `alpha`, `beta`, `production`; if omitted, defaults to `production`
- If the path is `/oauth`, the allowed parameters are:
  - `env` - see above
  - `token` - required, this is an opaque string that is forwarded to external auth services
  - `provider` - required, this is an opaque string, that is forwarded to external auth services
- Additional query parameters are interpreted as key-value map of extras
- The fragment **MUST NOT** be specified.

## Processing

The `username` part, if present, is **once** URL-decoded and interpreted as the username.

The `password` part, if present, is **once** URL-decoded and interpreted as the password.

The `host` part is interpreted as the Cloud ID, with an optionally trailing `*` which signifies an editable copy.

The `env` query parameter specifies which portal instance to use.


The extras are used as a key-value map of strings and are available as placeholders in the `global[...]` scope.
If the key is a duplicate, the first occurrence is used and the rest are ignored.

## Examples

```text title="Basic CSC link with username and password"
csc://user%40example.com:password123@mycloudid
```

| Parameter  | Value              |
|------------|--------------------|
| `username` | `user@example.com` |
| `password` | `password123`      |
| `Cloud ID` | `MYCLOUDID`        |

```text title="Editable Cloud ID without credentials"
csc://mycloudid*
```

| Parameter  | Value       |
|------------|-------------|
| `username` | (not set)   |
| `password` | (not set)   |
| `Cloud ID` | `MYCLOUDID` |

```text title="Username-only CSC link"
csc://user%40example.com@mycloudid
```

| Parameter  | Value              |
|------------|--------------------|
| `username` | `user@example.com` |
| `password` | (not set)          |
| `Cloud ID` | `MYCLOUDID`        |

```text title="CSC link with extra parameters"
csc://user%40example.com:password123@mycloudid?customHost=mysiphost.example.com
```

| Parameter     | Value              |
|---------------|--------------------|
| `username`    | `user@example.com` |
| `password`    | `password123`      |
| `Cloud ID`    | `MYCLOUDID`        |

Extra parameters available for placeholder resolution

| Parameter            | Value                   |
|----------------------|-------------------------|
| `global[customHost]` | `mysiphost.example.com` |