Edit in Dokuwiki Edit in Asciidoc Edit in Markdown
URL authentication

With URL authentication it is possible to provide an authentication method, credentials, and a proxy config to URL endpoints for different pre-processor commands like !include, !import or %load_json.

The authentication data is not stored in a DSL script, but in extra configuration files to which PlantUML must have access. The folder for the user data can be defined via a property.

Which authentication method with which user data should be performed for an endpoint is decided by a special notation in the URL. PlantUML interprets the UserInfo of the authority part of a URL as the name for the configuration.

Examples:

@startuml

!include https://access@raw.example.com/stash/repository/architecture/master/modelbase.puml

!$DATA = %load_json('https://service-cred@localhost/api/rest/endpoint?format=json)

' Embedded rendering of JSON structure

 rectangle Test #tan as "
    {{json
    $DATA
    }}
    Example JSON data
    "
' ...
@enduml

For the examples above, PlantUML needs two files (access.credential and service-cred.credential) in the folder configured by the property plantuml.security.credentials.path. Both files are structured as JSON and must be encoded in UTF-8.

By default, PlantUML only allows authentication for https URLs, since the credentials must be transmitted in encrypted form. If logins should also be allowed to go to unencrypted connections, the plantuml.security.allowNonSSLAuth property must be set to true. This is not under any circumstances recommended for connections that access servers on the internet.

Actually, PlantUML supports three kinds of authentication: Basic Auth, OAuth2, and raw token authentication. For the OAuth2 the grant types client_credential and password are supported. With the raw token authentication, it's possible to pass throw a manually generated token (e.g. API key, bearer token) to the URL endpoint.

Edit in Dokuwiki Edit in Asciidoc Edit in Markdown
Credentials configuration

A credentials configuration file must be stored in the folder configured by the property plantuml.security.credentials.path. The file extension is .credential, the file content is structured in JSON, the charset encoding is UTF-8, the filename must match the UserInfo part of the URL.

General JSON structure:

{
  "name": "<name of the configuration>",
  "type": "<type of the authentication method>",
  "identifier": "<client identifier>",
  "secret": "<client secret>",
  "properties": {
    "<key1>": "<value1>",
    "<key2>": "<value2>"
  },
  "proxy": {
    "type": "<proxy type>",
    "address": "<proxy server address>",
    "port": "<proxy server port>"
  }
}

name: required

The name of the configuration and should be similar to the file name

type: (basicauth, oauth, tokenauth), default: basicauth

Type of the authentication method

identifier: required

Client identifier name (user name, client id, principal, app key, ...)

secret:

Secret for the identifier in clear text (not encrypted)

properties:

Optional authentication-method specific properties. Properties should be defined as key-value pairs. A value can itself be a set of key-value pairs.

proxy:

Optional proxy configuration (overrides system proxy settings)

proxy.type: required (direct, socks, http)

Proxy type definition.

proxy.address: required

Proxy server address (hostname, IP address)

proxy.port:

Proxy server port number

Notes:

The name of a configuration may only contain characters from the following set: [a-z], [A-Z], [0-9], and "-". Not more than 64 characters are allowed.

The following pages describe the individual configuration options of the authentication methods:

Edit in Dokuwiki Edit in Asciidoc Edit in Markdown
Proxy configuration

A credential configuration can define a proxy configuration to override the system proxy configuration (e.g. via environment variables).

General Proxy structure:

{
  "type": "<proxy type>",
  "address": "<proxy server address>",
  "port": "<proxy server port>"
}

Any authentication configuration can define its own proxy definition. Three kinds of proxy types are allowed: direct, socks and http.

direct

Represents a direct connection or the absence of a proxy.

socks

Represents a SOCKS (V4 or V5) proxy.

http

Represents proxy for high-level protocols such as HTTP or FTP.

With direct an address and port are not required (and will be ignored).

address

Hostname or IP address of the proxy server

port

Port number of the proxy host.

Edit in Dokuwiki Edit in Asciidoc Edit in Markdown
Property configuration

Folder with credentials files

plantuml.security.credentials.path

Value: path to an existing folder with a read access for PlantUML

PlantUML needs a property with a configuration value to define a folder with the credentials files. Without the configured folder, the URL authentication is completely disabled and all UserInfo parts in URLs will be silently ignored.

The configuration value can be set as an environment variable or should be passed as -D parameter to the PlantUML JAR.

Example

java -jar PlantUML.jar -Dplantuml.security.credentials.path=/opt/mycomp/plantuml/security/credentials/

Edit in DokuwikiEdit in AsciidocEdit in MarkdownURL authentication

Edit in DokuwikiEdit in AsciidocEdit in MarkdownCredentials configuration

Edit in DokuwikiEdit in AsciidocEdit in MarkdownProxy configuration

Edit in DokuwikiEdit in AsciidocEdit in MarkdownProperty configuration

Edit in Dokuwiki Edit in Asciidoc Edit in Markdown
URL authentication

Edit in Dokuwiki Edit in Asciidoc Edit in Markdown
Credentials configuration

Edit in Dokuwiki Edit in Asciidoc Edit in Markdown
Proxy configuration

Edit in Dokuwiki Edit in Asciidoc Edit in Markdown
Property configuration