Kerberos

Kerberos is a network authentication protocol that uses secret-key cryptography to provide a secure authentication between server and client. Atlas system uses Kerberos protocol to authenticate users on domain servers such as Active Directory and LDAP.

Ticket Operations

Kerberos tickets allow users to authenticate to the kerberized services(applications) without entering another username and password after the initial authentication. In order to have kerberos tickets, one must get a Ticket Granting Ticket (TGT). The ticket operations include: obtaining a TGT and listing/destroying all tickets.

Obtain TGT

You can use this route to obtain a Ticket Granting Ticket from your Key Distribution Center (KDC). A TGT is required to join a domain as well as to get service tickets which you will need for the Samba service. Please pass the Kerberos server’s realm, admin username, and admin password in order to obtain a TGT.

Request Object

+ URL
  /api/v2/kerberos/ticket/obtain

+ Method
  POST

+ Headers
  Content-Type: application/json
  token: ThisIsNotARealTokenGenerateYourOwnToken

+ Body
  {}

Response Object

You should get a success message in your response body. To check your TGT, please use List Tickets route.

+ Headers
  X-Powered-By: OpenDrives
  Access-Control-Allow-Origin: *
  Content-Type: application/json; charset=utf-8

+ Body
  {
    "message": "Successfully obtained a ticket-granting ticket from the realm, EXAMPLE.COM"
  }

List Tickets

Using this route, you can list all Kerberos tickets including your TGT.

Request Object

+ URL
  /api/v2/kerberos/ticket/list

+ Method
  GET

+ Headers
  Content-Type: application/json
  token: ThisIsNotARealTokenGenerateYourOwnToken

+ Body
  {}

Response Object

The response should includes the location of Kerberos ticket cache, default principal, service principals, the ticket’s starting/expiring dates, and renew date.

+ Headers
  X-Powered-By: OpenDrives
  Access-Control-Allow-Origin: *
  Content-Type: application/json; charset=utf-8

+ Body
  {
    "raw": "Ticket cache: FILE:/tmp/krb5cc_0\nDefault principal: administrator@EXAMPLE.COM\n\nValid starting       Expires              Service principal\n12/08/2020 17:47:08  12/09/2020 03:47:08  krbtgt/EXAMPLE.COM@EXAMPLE.COM\n\trenew until 12/09/2020 17:47:08\n"
  }

Destroy Tickets

Send this request to destroy all Kerberos tickets.

Request Object

+ URL
  /api/v2/kerberos/ticket/destroy

+ Method
  POST

+ Headers
  Content-Type: application/json
  token: ThisIsNotARealTokenGenerateYourOwnToken

+ Body
  {}

Response Object

If successfully destroyed all Kerberos tickets, you will get a success message in your response body.

+ Headers
  X-Powered-By: OpenDrives
  Access-Control-Allow-Origin: *
  Content-Type: application/json; charset=utf-8

+ Body
  {
    "message": "Successfully destroyed all Kerberos tickets"
  }

Global Configuration Operations

Get/Update the global Kerberos configurations. If you update the global configuration file, the parameters you add/remove will affect every domains in your individual configuration files. Please do not remove includedir /etc/krb5.conf.d on the top of the global configuration file; this line includes all individual configuration files in other directory to the global configuration file.

Get Global Kerberos Configuration File

You can use this route to get the global Kerberos configuration file: krb5.conf.

Request Object

+ URL
  /api/v2/kerberos/conf

+ Method
  GET

+ Headers
  Content-Type: application/json
  token: ThisIsNotARealTokenGenerateYourOwnToken

+ Body
  {}

Response Object

You will get a raw and JSON parsed output of the global Kerberos configuration file.

+ Headers
  X-Powered-By: OpenDrives
  Access-Control-Allow-Origin: *
  Content-Type: application/json; charset=utf-8

+ Body
  {
    "raw": "includedir /etc/krb5.conf.d/\n\n[logging]\n\tdefault = FILE:/var/log/krb5libs.log\n\tkdc = FILE:/var/log/krb5kdc.log\n\tadmin_server = FILE:/var/log/kadmind.log\n\n[libdefaults]\n\tdns_lookup_realm = false\n\tkdc_timesynce = 1\n\tccache_type = 4\n\tforwardable = true\n\tdefault_keytab_name = FILE:/etc/krb5.keytab\n\tdns_lookup_kdc = true\n",
    "json": {
      "logging": {
        "default": "FILE:/var/log/krb5libs.log",
        "kdc": "FILE:/var/log/krb5kdc.log",
        "admin_server": "FILE:/var/log/kadmind.log"
      },
      "libdefaults": {
        "dns_lookup_realm": "false",
        "kdc_timesynce": "1",
        "ccache_type": "4",
        "forwardable": "true",
        "default_keytab_name": "FILE:/etc/krb5.keytab",
        "dns_lookup_kdc": "true"
      }
    }
  }

Update Global Kerberos Configuration File

Update the global Kerberos configuration file using this route. Configurations that you update will be applied to all individual domains. Please pass the contents of configurations file in raw string.

Request Object

+ URL
  /api/v2/kerberos/conf/update

+ Method
  POST

+ Parameters
  name (string, required, URL param) - The name of the domain SSSD configuration file you would like to view; you don't need to include the file extension. (e.g. /api/v2/sssd/domain/examplecom/details)

+ Headers
  Content-Type: application/json
  token: ThisIsNotARealTokenGenerateYourOwnToken

+ Body
  {
    "conf": "includedir /etc/krb5.conf.d/\n\n[logging]\n\tdefault = FILE:/var/log/krb5libs.log\n\tkdc = FILE:/var/log/krb5kdc.log\n\tadmin_server = FILE:/var/log/kadmind.log\n\n[libdefaults]\n\tdns_lookup_realm = false\n\tkdc_timesynce = 1\n\tccache_type = 4\n\tforwardable = true\n\tdefault_keytab_name = FILE:/etc/krb5.keytab\n\tdns_lookup_kdc = true\n"
  }

Response Object

Sending this should get you back a valid response, an empty object.

+ Headers
  X-Powered-By: OpenDrives
  Access-Control-Allow-Origin: *
  Content-Type: application/json; charset=utf-8

+ Body
  {}

Individual Realm Configuration Operations

List Individual Realm Configuration File

List, create, get, update, and delete an individual Kerberos realm configuration file. All individual files will be automatically included into the global configuration file by includedir parameter in krb5.conf.

Request Object

+ URL
  /api/v2/kerberos/realm

+ Method
  GET

+ Headers
  Content-Type: application/json
  token: ThisIsNotARealTokenGenerateYourOwnToken

+ Body
  {}

Response Object

You will get an object that’s keys are individual file names. Each key’s value is an object that has two properties: raw and json.

+ Headers
  X-Powered-By: OpenDrives
  Access-Control-Allow-Origin: *
  Content-Type: application/json; charset=utf-8

+ Body
  {
    "applefarmlocal": {
      "raw": "[realms]\n\tEXAMPLE.COM = {\n\t\tkdc = ldap01.example.com\n\t\tadmin_server = ldap01.example.com\n\t}\n\n[domain_realm]\n\t.example.com = EXAMPLE.COM\n\texample.com = EXAMPLE.COM\n",
      "json": {
        "realms": {
          "EXAMPLE.COM": {
            "kdc": [
              "ldap01.example.com"
            ],
            "admin_server": "ldap01.example.com"
          }
        },
        "domain_realm": {
          ".example.com": "EXAMPLE.COM",
          "example.com": "EXAMPLE.COM"
        }
      }
    }
  }

Create Individual Realm Configuration File

Create a new individual realm configuration file by passing name and conf in your request body; name must be in string, and conf can be either raw string or object.

Request Object

+ URL
  /api/v2/kerberos/realm/create

+ Method
  POST

+ Headers
  Content-Type: application/json
  token: ThisIsNotARealTokenGenerateYourOwnToken

+ Body
  {
    "name": "ldap02.example.com",
    "conf": {
      realms: {
        "EXAMPLE.COM": {
          kdc: ["ldap02.example.com", "ldap03.example.com"],
          admin_server: "ldap01.example.com"
        },
      },
      domain_realm: {
        ".example.com": "EXAMPLE.COM",
        "example.com": "EXAMPLE.COM",
      }
    }
  }

Response Object

You will get an empty object when you successfully create an individual configuration file.

+ Headers
  X-Powered-By: OpenDrives
  Access-Control-Allow-Origin: *
  Content-Type: application/json; charset=utf-8

+ Body
  {}

Get Individual Realm Configuration File

Read an existing individual realm configuration file by passing the file name as a parameter in the URL.

Request Object

+ URL
  /api/v2/kerberos/realm/$NAME/details

+ Method
  GET

+ Parameters
  name (string, required, URL param) - The name of the individual realm configuration file you want to read; you don't need to include the file extension. (e.g. /api/v2/kerberos/realm/examplecom/details)

+ Headers
  Content-Type: application/json
  token: ThisIsNotARealTokenGenerateYourOwnToken

+ Body
  {}

Response Object

The response body will have raw and JSON parsed output of the individual realm configuration file you’ve requested.

+ Headers
  X-Powered-By: OpenDrives
  Access-Control-Allow-Origin: *
  Content-Type: application/json; charset=utf-8

+ Body
  {
    "raw": "[realms]\n\tEXAMPLE.COM = {\n\t\tkdc = ldap01.example.com\n\t\tadmin_server = ldap01.example.com\n\t}\n\n[domain_realm]\n\t.example.com = EXAMPLE.COM\n\texample.com = EXAMPLE.COM\n",
    "json": {
      "realms": {
        "EXAMPLE.COM": {
          "kdc": ["ldap01.example.com"],
          "admin_server": "ldap01.example.com"
        }
      },
      "domain_realm": {
        ".example.com": "EXAMPLE.COM",
        "example.com": "EXAMPLE.COM"
      }
    }
  }

Update Individual Realm Configuration File

Update an existing individual realm configuration file. Please pass the name of the file you want to update in the URL as a parameter and pass the configurations in request body as conf.

Request Object

+ URL
  /api/v2/kerberos/realm/$NAME/update

+ Method
  POST

+ Parameters
  name (string, required, URL param) - The name of the individual realm configuration file you want to update; you don't need to include the file extension. (e.g. /api/v2/kerberos/realm/examplecom/update)

+ Headers
  Content-Type: application/json
  token: ThisIsNotARealTokenGenerateYourOwnToken

+ Body
  {
    "conf": {
      realms: {
        "EXAMPLE.COM": {
          kdc: ["ldap02.example.com", "ldap03.example.com"],
          admin_server: "ldap01.example.com"
        },
      },
      domain_realm: {
        ".example.com": "EXAMPLE.COM",
        "example.com": "EXAMPLE.COM",
      }
    }
  }

Response Object

An empty object will return if the request was successful.

+ Headers
  X-Powered-By: OpenDrives
  Access-Control-Allow-Origin: *
  Content-Type: application/json; charset=utf-8

+ Body
  {}

Delete Individual Realm Configuration File

Delete an existing individual realm configuration file. Please pass the name of the file you want to delete in the URL as a parameter.

Request Object

+ URL
  /api/v2/kerberos/realm/$NAME/delete

+ Method
  POST

+ Parameters
  name (string, required, URL param) - The name of the individual realm configuration file you want to delete; you don't need to include the file extension. (e.g. /api/v2/kerberos/realm/examplecom/delete)

+ Headers
  Content-Type: application/json
  token: ThisIsNotARealTokenGenerateYourOwnToken

+ Body
  {}

Response Object

You will get a success message after deleting the individual realm configuration file.

+ Headers
  X-Powered-By: OpenDrives
  Access-Control-Allow-Origin: *
  Content-Type: application/json; charset=utf-8

+ Body
  {
    "message": "Successfully deleted examplecom.conf"
  }