Configuring credentials
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"
import (
auth "github.com/pip-services4/pip-services4-go/pip-services4-config-go/auth"
)
from pip_services4_config.auth import CredentialParams
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'}
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'}
# 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'}
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");
credential := auth.NewCredentialParamsFromTuples("username", "userA", "pin", "321", "credentialA", "a") // Returns {'username': 'userA', 'pin': '321', 'credentialA': 'a'}
credential = CredentialParams.from_tuples("username","userA","pin", "321",'credentialA','a') # Returns {'username': 'userA', 'pin': '321', 'credentialA': 'a'}
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"}
credential := auth.NewCredentialParamsFromString("user=jdoe;pass=pass1") // Returns {'user': "'jdoe'", 'pass': "'pass1'"}
credential = CredentialParams.from_string("user=jdoe;pass=pass1") # Returns {"user": "jdoe", "pass": "pass1"}
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'}
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'}
config = ConfigParams.from_tuples("credential.user", "user1",
"credential.password", "password1")
credential = CredentialParams.from_config(config) # Returns {'user': 'user1', 'password': 'password1'}
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'}]
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]
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'}]
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'}
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]
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'}
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'
credential[0].AccessId()
credential[0].AccessKey()
credential[0].Password()
credential[0].Username()
credential[0].StoreKey()
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'
Additionally, we can use the get method, which takes the name of the credential parameter as its input.
credential[0].get("username"); // Returns 'user1'
credential[0].Get("username")
credential[0].get('username') # Returns 'user1'
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");
credential[0].SetPassword("password2")
credential[0].set_password('password2')
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");
credential[0].Put("password", "password3")
credential[0].put('password', 'password3')
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");
credential[0].SetAsObject("password", "password4")
credential[0].set_as_object('password', 'password4')
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'}
config := conf.NewConfigParamsFromTuples("password", "password5")
overriden := credential[0].Override(config)
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'}
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");
overriden[0].Remove("username")
overriden.remove('username')
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"
import (
auth "github.com/pip-services4/pip-services4-go/pip-services4-config-go/auth"
)
from pip_services4_config.auth import MemoryCredentialStore
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);
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)
config = ConfigParams.from_tuples("key1.user", "jdoe",
"key1.pass", "pass123",
"key2.user", "bsmith",
"key2.pass", "mypass"
)
credentialStore = MemoryCredentialStore(config)
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);
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)
config = ConfigParams.from_tuples("key1.user", "jdoe",
"key1.pass", "pass123",
"key2.user", "bsmith",
"key2.pass", "mypass"
)
credentialStore = MemoryCredentialStore()
credentialStore.read_credentials(config)
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);
credential := auth.NewCredentialParams(conf.NewConfigParamsFromTuples(
"user", "jdoe3", "password", "pass123345", "pin", "321345",
).Value())
credentialStore.Store(context.Background(), "key2", credential)
credential = CredentialParams.from_tuples("user", "jdoe3", "password", "pass123345", "pin", "321345")
credentialStore.store(None, "key2", credential)
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'}
result, _ := credentialStore.Lookup(context.Background(), "key2")
fmt.Println(result) // Returns user=jdoe3;password=pass123345;pin=321345
result = credentialStore.lookup("123", "key2")
result # Returns {'user': 'bsmith', 'pass': 'mypass'}
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);
credential1 := auth.NewCredentialParams(conf.NewConfigParamsFromTuples(
"user", "jdoe3V2", "password", "pass123345", "pin", "321345",
).Value())
credentialStore.Store(context.Background(), "key3", credential1)
}
credential = CredentialParams.from_tuples("user", "jdoe3V2", "password", "pass123345", "pin", "321345")
credentialStore.store(None, "key3", credential)
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);
config = conf.NewConfigParamsFromTuples(
"key1.user", "jdoeV2",
"key1.pass", "pass123",
"key4.user", "bsmith",
"key4.pass", "mypass",
)
credentialStore.ReadCredentials(config)
config = ConfigParams.from_tuples(
"key1.user", "jdoeV2",
"key1.pass", "pass123",
"key4.user", "bsmith",
"key4.pass", "mypass"
)
credentialStore.read_credentials(config)
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);
credentialStore.Store(context.Background(), "key3", nil)
credentialStore.store(None, "key3", None)
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.