Configuring credentials

How to configure credentials using Pip.Services.

Key takeaways

CredentialParams Component used to store credential parameters and their values.
ConfigParams Parent class that provides several useful methods.
StringValueMap Class that provides the structure for CredentialParams.
MemoryCredentialStore Class used to create a store in memory for credential parameters.

Introduction

In this tutorial, you will learn how to use the CredentialParams component to perform CRUD operations. We will start by creating an instance of this component using its constructor, a tuple, a string, and the ConfigParam class. Then, we will learn how to extract, update, and delete the values of credential parameters stored in the component.

CredentialParams

Pre-requisites

In order to use the CredentialParams component, we need to import it first. This can be done with the following command:

import { CredentialParams } from "pip-services4-config-node"
Not available
import (
    auth "github.com/pip-services4/pip-services4-go/pip-services4-config-go/auth"
)
Not available
from pip_services4_config.auth import CredentialParams

Not available

CRUD operations

Once the component has been imported, we can do different CRUD operations by using the methods of the class and those inherited from the parent classes (ConfigParams and StringValueMap).

Create

Pip.Services offers several ways to create a CredentialParams object. Each of them is explained in the following sections.

a) Using the constructor

One method used to create a CredentialParams object is via its constructor. This can be done in two different manners. The first is by inputting a ConfigParams object containing the credential parameters and their values. The second consists of creating a CredentialParams object and using the set methods available for the most common credentials such as username and password, or the put() method from its parent class. The following examples show how to do this.

import { CredentialParams } from "pip-services4-config-node"
import { ConfigParams } from "pip-services4-components-node"

// Case 1: Constructor + ConfigParams object
let config = ConfigParams.fromTuples("user", "user1", "password", "password1");
let credential = new CredentialParams(config); // Returns {'credential.user': 'user1', 'credential.password': 'password1'}

// Case 2: Constructor + set/put methods
credential = new CredentialParams();
credential.setUsername("user1");
credential.setPassword("password1");
credential.setStoreKey("store key1");
credential.setAccessKey("access key 1");
credential.setAccessId("access id 1");
credential.put("parameter1", "value1");

credential
// Returns
// {'username': 'user1',
// 'password': 'password1',
// 'store_key': 'store key1',
// 'access_key': 'access key 1',
// 'access_id': 'access id 1'
// 'parameter1': 'value1'}
Not available
import (
	"fmt"

	conf "github.com/pip-services4/pip-services4-go/pip-services4-components-go/config"
	auth "github.com/pip-services4/pip-services4-go/pip-services4-config-go/auth"
)

// Case 1: Constructor + ConfigParams object
config := conf.NewConfigParamsFromTuples(
	"user", "user1",
	"password", "password1",
)
credential := auth.NewCredentialParams(config.Value()) // Returns {'credential.user': 'user1', 'credential.password': 'password1'}

// Case 2: Constructor + set/put methods
credential = auth.NewEmptyCredentialParams()
credential.SetUsername("user1")
credential.SetPassword("password1")
credential.SetStoreKey("store key1")
credential.SetAccessKey("access key 1")
credential.SetAccessId("access id 1")
credential.Put("parameter1", "value1")

fmt.Println(credential)
// Returns
//{'username': 'user1',
// 'password': 'password1',
// 'store_key': 'store key1',
// 'access_key': 'access key 1',
// 'access_id': 'access id 1'
// 'parameter1': 'value1'}
Not available
# Case 1: Constructor + ConfigParams object
config = ConfigParams.from_tuples("user",  "user1", 
                                   "password", "password1")
credential = CredentialParams(config) # Returns {'credential.user': 'user1', 'credential.password': 'password1'}

# Case 2: Constructor + set/put methods
credential = CredentialParams()
credential.set_username("user1")
credential.set_password("password1")
credential.set_store_key("store key1")
credential.set_access_key("access key 1")
credential.set_access_id("access id 1")
credential.put("parameter1", "value1") 
credential
# Returns
#{'username': 'user1',
# 'password': 'password1',
# 'store_key': 'store key1',
# 'access_key': 'access key 1',
# 'access_id': 'access id 1'
# 'parameter1': 'value1'}

Not available
b) Using a tuple

We can also define our credential parameters in the form of a tuple by using the fromTuple() method. For example:

let credential = CredentialParams.fromTuples("username", "userA", "pin", "321", "credentialA", "a");
Not available
credential := auth.NewCredentialParamsFromTuples("username", "userA", "pin", "321", "credentialA", "a") // Returns {'username': 'userA', 'pin': '321', 'credentialA': 'a'}
Not available
credential = CredentialParams.from_tuples("username","userA","pin", "321",'credentialA','a') # Returns {'username': 'userA', 'pin': '321', 'credentialA': 'a'}
Not available
c) Using a string

Similar to the previous option, we can also use a string to define our credential parameters via the fromString() method. The syntax of the string is:

parameter_name : parameter_value

An example of this approach is:

let credential = CredentialParams.fromString("user=jdoe;pass=pass1"); // Returns {"user": "jdoe", "pass": "pass1"}

Not available
credential := auth.NewCredentialParamsFromString("user=jdoe;pass=pass1") // Returns {'user': "'jdoe'", 'pass': "'pass1'"}
Not available
credential = CredentialParams.from_string("user=jdoe;pass=pass1") # Returns {"user": "jdoe", "pass": "pass1"}
Not available
d) Using a ConfigParams object

Also, we can create a ConfigParams object and use the fromConfig() method. In this case, we need to use a section named credential, which will include our parameters and their values, and add the ConfigParams object as an input to that method. The syntax for the parameters is as follows:

credential.parameterName

And, the following example explains how to use this method:

import { CredentialParams } from "pip-services4-config-node"
import { ConfigParams } from "pip-services4-components-node"

let config = ConfigParams.fromTuples("credential.user", "user1", "credential.password", "password1");
let credential = CredentialParams.fromConfig(config); // Returns {'user': 'user1', 'password': 'password1'}

Not available
import (
	conf "github.com/pip-services4/pip-services4-go/pip-services4-components-go/config"
	auth "github.com/pip-services4/pip-services4-go/pip-services4-config-go/auth"
)

config := conf.NewConfigParamsFromTuples("credential.user", "user1", "credential.password", "password1")
credential := auth.NewCredentialParamsFromConfig(config) // Returns {'user': 'user1', 'password': 'password1'}
Not available
config = ConfigParams.from_tuples("credential.user",  "user1", 
                                   "credential.password", "password1")
credential = CredentialParams.from_config(config) # Returns {'user': 'user1', 'password': 'password1'}
Not available
e) Using the manyFromConfig() method

This method allows us to define several credential parameter sets in one CredentialParams object. For this, we use a section named credentials that contains the different sets. The syntax is as follows:

credentials.credentialSetName.parameterName

Then, at instantiation, the CredentialParams object will take all credentials belonging to this section.

The following example shows how to do this. As we can see from it, the ConfigParams object contains both credential and connection parameters. However, the CredentialParams object distinguishes between them and only takes the credential sets in the form of a list.

let config = ConfigParams.fromTuples(
    // use connection if one connection and connections if more than one connection
    "connections.connection1.uri", "http://www.example1.com",
    "connections.connection1.protocol", "http",
    "connections.connection1.host", "host152",
    "connections.connection1.my_conn_parameter", "value1",
    "connections.connection2.uri", "http://www.example2.com",
    "connections.connection2.protocol", "http",
    "connections.connection2.host", "host153",
    "connections.connection2.my_conn_parameter", "value3",
    // use credential if one credential and credentials if more than one credential
    "credentials.database1.username", "user1",
    "credentials.database1.password", "userpass123",
    "credentials.database2.username", "user2",
    "credentials.database2.password", "userpass457",
    "credentials.database2.my_custom_credential_param", "myvalue"
);

let credential = CredentialParams.manyFromConfig(config);

// Returns [{'username': 'user1', 'password': 'userpass123'}, {'username': 'user2',  'password': 'userpass457','my_custom_credential_param': 'myvalue'}]

Not available
config := conf.NewConfigParamsFromTuples(
	// use connection if one connection and connections if more than one connection
	"connections.connection1.uri", "http://www.example1.com",
	"connections.connection1.protocol", "http",
	"connections.connection1.host", "host152",
	"connections.connection1.my_conn_parameter", "value1",
	"connections.connection2.uri", "http://www.example2.com",
	"connections.connection2.protocol", "http",
	"connections.connection2.host", "host153",
	"connections.connection2.my_conn_parameter", "value3",
	// use credential if one credential and credentials if more than one credential
	"credentials.database1.username", "user1",
	"credentials.database1.password", "userpass123",
	"credentials.database1.store_key", "store_key1",
	"credentials.database1.access_key", "access_key1",
	"credentials.database1.access_id", "access_id1",

	"credentials.database2.username", "user2",
	"credentials.database2.password", "userpass457",
	"credentials.database2.store_key", "store_key2",
	"credentials.database2.access_key", "access_key2",
	"credentials.database2.access_id", "access_id2",
	"credentials.database2.my_custom_credential_param", "myvalue",
)

credential := auth.NewManyCredentialParamsFromConfig(config)
// Returns [store_key=store_key2;
// access_key=access_key2;
// my_custom_credential_param=myvalue;
// access_id=access_id2;
// password=userpass457;
// username=user2
// access_key=access_key1;
// password=userpass123;
// username=user1;
// store_key=store_key1;
// access_id=access_id1]
Not available
config = ConfigParams.from_tuples(
    # use connection if one connection and connections if more than one connection
    "connections.connection1.uri", "http://www.example1.com",
    "connections.connection1.protocol", "http",
    "connections.connection1.host", "host152",
    "connections.connection1.my_conn_parameter", "value1",
    "connections.connection2.uri", "http://www.example2.com",
    "connections.connection2.protocol", "http",
    "connections.connection2.host", "host153",
    "connections.connection2.my_conn_parameter", "value3",
    # use credential if one credential and credentials if more than one credential
    "credentials.database1.username", "user1",
    "credentials.database1.password", "userpass123",
    "credentials.database2.username", "user2",
    "credentials.database2.password", "userpass457",
    "credentials.database2.my_custom_credential_param", "myvalue"
)

credential = CredentialParams.many_from_config(config) 
# Returns [{'username': 'user1', 'password': 'userpass123'}, {'username': 'user2',  'password': 'userpass457','my_custom_credential_param': 'myvalue'}]


Not available
Adding a section

We can add a section by using the addSection() method inherited from the ConfigParams class. This method accepts the name of the section and a ConfigParams object containing the fields of the section and their values as inputs. The following example shows how to do this:

credential[0].addSection("sectionA", ConfigParams.fromTuples("key1", "ABCDE"));
// Returns
// {'username': 'user1',
// 'password': 'password1',
// 'store_key': 'store key1',
// 'access_key': 'access key 1',
// 'access_id': 'access id 1',
// 'sectionA.key1': 'ABCDE'}
Not available
credential[0].AddSection("sectionA", conf.NewConfigParamsFromTuples("key1", "ABCDE"))
// Returns [store_key=store_key2;
// access_key=access_key2;
// my_custom_credential_param=myvalue;
// access_id=access_id2;
// password=userpass457;
// username=user2
// access_key=access_key1;
// password=userpass123;
// username=user1;
// store_key=store_key1;
// access_id=access_id1;
// sectionA.key1=ABCDE]
Not available
credential[0].add_section("sectionA", ConfigParams.from_tuples("key1", "ABCDE"))
# Returns
# {'username': 'user1',
# 'password': 'password1',
# 'store_key': 'store key1',
# 'access_key': 'access key 1',
# 'access_id': 'access id 1',
# 'sectionA.key1': 'ABCDE'}

Not available

Read

To extract the values of the different credential parameters, we can use the get methods available for the most common credential parameters such as username, password, and access key. The following examples show how to use them:

credential[0].getAccessId();   // Returns 'access id 1'
credential[0].getAccessKey();  // Returns 'access key 1'
credential[0].getPassword();   // Returns 'password1'
credential[0].getUsername();   // Returns 'user1'
credential[0].getStoreKey();   // Returns 'store key1'
Not available
credential[0].AccessId()  
credential[0].AccessKey() 
credential[0].Password()  
credential[0].Username()  
credential[0].StoreKey()  
Not available
credential[0].get_access_id()   # Returns 'access id 1'
credential[0].get_access_key()  # Returns 'access key 1'
credential[0].get_password()    # Returns 'password1'
credential[0].get_username()    # Returns 'user1'
credential[0].get_store_key()   # Returns 'store key1'
Not available

Additionally, we can use the get method, which takes the name of the credential parameter as its input.

credential[0].get("username");   // Returns 'user1'
Not available
credential[0].Get("username")
Not available
credential[0].get('username')   # Returns 'user1'
Not available

Update

There are several ways to update a parameter’s value. One of them is to use the set method for the parameter with the new value as input. For example:

credential[0].setPassword("password2");
Not available
credential[0].SetPassword("password2")
Not available
credential[0].set_password('password2')
Not available

will reset the value of the password to ‘password2’.

Another way is to use the put() method, which asks for the name of the parameter and its new value as inputs:

credential[0].put("password", "password3");

Not available
credential[0].Put("password", "password3")
Not available
credential[0].put('password', 'password3')
Not available

Or, to use the setAsObject() method, which also takes the name of the credential parameter and its value as inputs.

credential[0].SetAsObject("password", "password4");

Not available
credential[0].SetAsObject("password", "password4")
Not available
credential[0].set_as_object('password', 'password4')
Not available

Finally, we can use the override() method, which returns a new instance of CredentialParams with the old and updated values. The following example explains how to use it:

let config = ConfigParams.fromTuples("password", "password5");
let overriden = credential[0].override(config);

// Returns
// {'username': 'user1',
// 'password': 'password5',
// 'store_key': 'store key1',
// 'access_key': 'access key 1',
// 'access_id': 'access id 1',
// 'parameter_name': 'new_parameter_value'}

Not available
config := conf.NewConfigParamsFromTuples("password", "password5")
overriden := credential[0].Override(config)
Not available
config = ConfigParams.from_tuples("password", "password5")
overriden = credential[0].override(config)
# Returns
#{'username': 'user1',
# 'password': 'password5',
# 'store_key': 'store key1',
# 'access_key': 'access key 1',
# 'access_id': 'access id 1',
# 'parameter_name': 'new_parameter_value'}
Not available

Delete

To delete a credential parameter from a CredentialParams object, we can use the remove() method, which takes the parameter’s name as input. This example explains how to use it:

overriden.remove("username");

Not available
overriden[0].Remove("username")
Not available
overriden.remove('username')
Not available

MemoryCredentialStore

The MemoryCredentialStore component is used to create a store for credential parameters. In it, each set of credentials is identified by a common key. The following sections explain how to create an instance of this class, add credentials to it, and modify and delete those credentials.

Pre-requisites

In order to create a MemoryCredentialStore component, we need to import this class first. This can be done with the following command:

import { MemoryCredentialStore } from "pip-services4-config-node"
Not available
import (
    auth "github.com/pip-services4/pip-services4-go/pip-services4-config-go/auth"
)
Not available
from pip_services4_config.auth import MemoryCredentialStore

Not available

Creating and configuring a store

To create a MemoryCredentialStore, we need to instantiate this class. This presents us with two different options: we can create a ConfigParams object containing the configuration parameters and call it from the constructor

import { MemoryCredentialStore } from "pip-services4-config-node"
import { ConfigParams } from "pip-services4-components-node"

let config = ConfigParams.fromTuples(
    "key1.user", "jdoe",
    "key1.pass", "pass123",
    "key2.user", "bsmith",
    "key2.pass", "mypass"
);
let credentialStore = new MemoryCredentialStore(config);
Not available
import (
	conf "github.com/pip-services4/pip-services4-go/pip-services4-components-go/config"
	auth "github.com/pip-services4/pip-services4-go/pip-services4-config-go/auth"
)


config := conf.NewConfigParamsFromTuples(
	"key1.user", "jdoe",
	"key1.pass", "pass123",
	"key2.user", "bsmith",
	"key2.pass", "mypass",
)

credentialStore := auth.NewManyCredentialParamsFromConfig(config)
Not available
config = ConfigParams.from_tuples("key1.user", "jdoe",
    "key1.pass", "pass123",
    "key2.user", "bsmith",
    "key2.pass", "mypass"
)

credentialStore = MemoryCredentialStore(config)

Not available

or we can instantiate the store without any input parameter and use the readCredentials() method to add the credentials:

import { MemoryCredentialStore } from "pip-services4-config-node"
import { ConfigParams } from "pip-services4-components-node"

let config = ConfigParams.fromTuples(
    "key1.user", "jdoe",
    "key1.pass", "pass123",
    "key2.user", "bsmith",
    "key2.pass", "mypass"
);

let credentialStore = new MemoryCredentialStore();
credentialStore.readCredentials(config);
Not available
import (
	conf "github.com/pip-services4/pip-services4-go/pip-services4-components-go/config"
	auth "github.com/pip-services4/pip-services4-go/pip-services4-config-go/auth"
)


config := conf.NewConfigParamsFromTuples(
	"key1.user", "jdoe",
	"key1.pass", "pass123",
	"key2.user", "bsmith",
	"key2.pass", "mypass",
)

credentialStore := auth.NewEmptyMemoryCredentialStore()
credentialStore.ReadCredentials(config)
Not available
config = ConfigParams.from_tuples("key1.user", "jdoe",
    "key1.pass", "pass123",
    "key2.user", "bsmith",
    "key2.pass", "mypass"
)

credentialStore = MemoryCredentialStore()
credentialStore.read_credentials(config)


Not available

Adding new credentials

To add new credentials to a store, we use the store() method. This method accepts the context, the identification key and a CredentialParams object containing the set of credentials as inputs. In the example below, we add a new set of credentials identified by a key with value “key3”.

let credential = new CredentialParams(ConfigParams.fromTuples("user", "jdoe3", "password", "pass123345", "pin", "321345"));
await credentialStore.store(ctx, "key2", credential);

Not available
credential := auth.NewCredentialParams(conf.NewConfigParamsFromTuples(
	"user", "jdoe3", "password", "pass123345", "pin", "321345",
).Value())

credentialStore.Store(context.Background(), "key2", credential)
Not available
credential = CredentialParams.from_tuples("user", "jdoe3", "password", "pass123345", "pin", "321345")
credentialStore.store(None, "key2", credential)
Not available

Reading the credentials

The lookup() method is used to retrieve stored credentials. It takes a context and a key as input parameters and returns a ConfigParams object containing the retrieved credentials. If no credentials were found, it returns an empty ConfigParams object.

let result = await credentialStore.lookup(ctx, "key2");
console.log(result); // Returns {'user': 'bsmith', 'pass': 'mypass'}
Not available
result, _ := credentialStore.Lookup(context.Background(), "key2")
fmt.Println(result) // Returns user=jdoe3;password=pass123345;pin=321345
Not available
result = credentialStore.lookup("123", "key2")
result # Returns {'user': 'bsmith', 'pass': 'mypass'}
Not available

Updating the credentials

Credentials can be updated with the store() method. This method requires the context, the key of the set we want to update and a CredentialParams object containing the updated parameters as inputs. In the following example, we change the value of the user to “joeve3V2”.

let credential1 = new CredentialParams(ConfigParams.fromTuples("user", "jdoe3V2", "password", "pass123345", "pin", "321345"));
await credentialStore.store(ctx, "key3", credential1);
Not available
credential1 := auth.NewCredentialParams(conf.NewConfigParamsFromTuples(
	"user", "jdoe3V2", "password", "pass123345", "pin", "321345",
).Value())

credentialStore.Store(context.Background(), "key3", credential1)
}
Not available
credential = CredentialParams.from_tuples("user", "jdoe3V2", "password", "pass123345", "pin", "321345")
credentialStore.store(None, "key3", credential)
Not available

Alternatively, we can change all the stored values with the readCredentials() method. In this case, all the stored sets will be deleted and the new ones stored. In the example below, we replace the set identified by “key1” with new values, delete the sets identified by “key2” and “key3”, and add a new set identified by “key4”.

config = ConfigParams.fromTuples(
    "key1.user", "jdoeV2",
    "key1.pass", "pass123",
    "key4.user", "bsmith",
    "key4.pass", "mypass"
);
credentialStore.readCredentials(config);
Not available
config = conf.NewConfigParamsFromTuples(
	"key1.user", "jdoeV2",
	"key1.pass", "pass123",
	"key4.user", "bsmith",
	"key4.pass", "mypass",
)

credentialStore.ReadCredentials(config)
Not available
config = ConfigParams.from_tuples(
    "key1.user", "jdoeV2",
    "key1.pass", "pass123",
    "key4.user", "bsmith",
    "key4.pass", "mypass"
)

credentialStore.read_credentials(config)
Not available

Deleting the credentials

We can delete a set of credentials identified by a common key by placing a Null/None value as the CredentialParams object in the store method. The following example shows how to do this:

await credentialStore.store(ctx, "key3", null);
Not available
credentialStore.Store(context.Background(), "key3", nil)
Not available
credentialStore.store(None, "key3", None)
Not available

Wrapping up

In this tutorial, we have learned how to create CredentialParams components and manage them by extracting and updating the stored values of the credentials, and deleting their parameters. We have also seen how to create and work with a MemoryCredentialStore component.