Help us improve your experience.

Let us know what you think.

Do you have time for a two-minute survey?

 
 

Configure gRPC Services

SUMMARY Configure the gRPC server to enable a client to use gRPC services, including gRPC Network Operations Interface (gNOI) services, gRPC Network Management Interface (gNMI) services, and gRPC Routing Information Base Interface (gRIBI) services, on the network device.

This topic discusses how to configure gRPC services on Junos devices, including the options for authentication and how to configure each option. Before the server and client can establish a gRPC session, you must satisfy the requirements discussed in the following sections:

Understanding Authentication for gRPC-based Services

The gNOI, gNMI, and gRIBI services use the gRPC Remote Procedure Call framework for transport. The gRPC server runs on the network device and listens for connection requests on a specified port. The gRPC client application runs on a remote network management system (NMS) and establishes a gRPC channel with the server on the specified host and port. The client executes RPCs through the SSL-encrypted gRPC session to perform network service operations. Figure 1 illustrates a simple connection between a gNOI client and server.

Figure 1: gNOI Server and Client Interaction gNOI Server and Client Interaction

gRPC channels use channel credentials to handle authentication between the server and the client. Standard channel credentials use X.509 digital certificates for authenticating the server and the client. A digital certificate provides a way of authenticating users through a trusted third-party called a certificate authority or certification authority (CA). The CA verifies the identity of a certificate holder and “signs” the certificate to attest that it has not been forged or altered. The X.509 standard defines the format for the certificate. Digital certificates can be used to establish a secure connection between two endpoints through certificate validation. To establish a gRPC channel, each endpoint (device or application) that requires authentication must supply an X.509 certificate in the exchange.

Junos devices support both server-only authentication as well as mutual authentication for SSL-based gRPC sessions. When server-only authentication is configured, the server provides its public key certificate when the channel is established. The client uses the server's Root CA certificate to authenticate the server. When mutual authentication is configured, the client also provides its certificate when it connects to the server, and the server validates the certificate. If the certificate validation is successful, the client is allowed to make calls. We recommend that you configure mutual authentication and use CA-signed certificates for the strongest security, although self-signed certificates are accepted.

A public key infrastructure (PKI) supports the distribution and identification of public encryption keys, enabling users to both securely exchange data over networks such as the Internet and verify the identity of the other party. For gRPC-based services, the Junos PKI must contain the certificate for the local device acting as the gRPC server. If you use mutual authentication, the Junos PKI must also contain the Root CA certificates required to validate the certificates of any gRPC clients that connect to the device.

Table 1 outlines the general requirements for server-only authentication and mutual authentication when a gRPC client connects to the device to perform gRPC-based services. The gRPC server's certificate must define either the server’s hostname in the Common Name (CN) field, or it must define the server’s IP address in the Subject Alternative Name (subjectAltName or SAN) IP Address field. The client application must use the same value to establish the connection to the server. If the certificate defines the SubjectAltName IP Address field, the Common Name field is ignored during authentication.

Table 1: Requirements for Server-Only and Mutual Authentication for gRPC Sessions
Requirements Server-only Authentication Mutual Authentication
Certificates

The server must have an X.509 public key certificate.

If the client connects to the server's IP address instead of the hostname, the server's certificate must include the subjectAltName (SAN) IP address extension field with the IP address of the server.

The server and client must each have an X.509 public key certificate.

If the client connects to the server's IP address instead of the hostname, the server's certificate must include the subjectAltName (SAN) IP address extension field with the IP address of the server.

Junos PKI

The server's local certificate must be loaded in the Junos PKI.

The server's local certificate and each client's Root CA certificate must be loaded in the Junos PKI.

Channel credentials

The client must pass in the server's Root CA certificate when the gRPC channel is established.

The client must pass in their certificate and key and the server's Root CA certificate when the gRPC channel is established.

Channel credentials are attached to the gRPC channel and enable the client application to access the service. Call credentials, on the other hand, are attached to a specific service operation (RPC request) and provide information about the person who is using the client application. Call credentials are sent per request, that is, for each RPC call. To execute gNOI operations on Junos devices, you must provide call credentials in the request. The user must either have a user account defined locally on the device, or the user must be authenticated by a TACACS+ server, which then maps the user to a user template account that is defined locally on the device. You can provide the call credentials (username and password) in the RPC's metadata argument. If authentication is successful, the Junos device executes the RPC request using the account privileges of the specified user.

Note:

As an alternative to passing in call credentials for every RPC executed on a Junos device, you can use the Juniper Extension Toolkit jnx_authentication_service API to log in to the device once at the start of the gRPC session, and all subsequent RPCs executed in the channel are authenticated. You can download the JET Client IDL library from the Juniper Networks download site.

Obtain X.509 Certificates

The SSL-encrypted gRPC session uses X.509 public key certificates to authenticate the gRPC server and client. For server-only authentication, the gRPC server must have a certificate. For mutual authentication, both the gRPC server and client must have certificates. The requirements for the certificates are:

  • The certificate can be signed by a certificate authority (CA) or self-signed.

  • The certificate must be PEM-encoded.

  • The gRPC server's certificate must define either the gRPC server’s hostname in the Common Name (CN) field, or it must define the gRPC server’s IP address in the SubjectAltName (SAN) IP Address field. The gRPC client must use the same value to establish the connection to the server. If the certificate defines the SubjectAltName IP Address, the Common Name field is ignored during authentication.

To use OpenSSL to obtain the gRPC server's certificate:

  1. Generate a private key, and specify the key length in bits.
  2. If the gRPC client connects to the gRPC server’s IP address, update your openssl.cnf or equivalent configuration file to define the subjectAltName=IP extension with the gRPC server’s IP address.
  3. Generate a certificate signing request (CSR), which contains the entity's public key and information about their identity.

    Alternatively, you can provide the CSR information in a single command, for example:

  4. Generate the certificate by doing one of the following:
    • Send the CSR to a certificate authority to request an X.509 certificate, and provide the configuration file to include any additional extensions.

    • Sign the CSR with a CA to generate the certificate, and include the -extfile option if you need to reference your configuration file and extensions.

    • Sign the CSR with the server key to generate a self-signed certificate, and include the -extfile option if you need to reference your configuration file and extensions.

  5. Verify that the certificate's Common Name (CN) field and extensions, if provided, are correct.

For mutual authentication, repeat the previous steps with the information for the gRPC client to generate the client's key and certificate. The client certificate does not require the SAN IP extension field.

Load the gRPC Server's Local Certificate in the Junos PKI

The network device running the gRPC server must have an X.509 certificate that identifies the device to gRPC clients. To perform gRPC-based services on the Junos device, you must load the public key certificate and key for the local network device in the Junos PKI. After you load the certificate and perform the initial configuration, gNOI clients can then use the certificate management (cert) service to install a new certificate or replace the existing certificate.

To load the local device's certificate and key in the PKI:

  1. Download the certificate and key for the device that is acting as the gRPC server to that device.
  2. In operational mode, define an identifier and load the local device's certificate and key into the PKI.
  3. (Optional) Verify the certificate is present in the PKI database.

Enable gRPC Services

gRPC-based services use an API connection setting based on Secure Socket Layer (SSL) technology. For an SSL-based connection, you must specify a local-certificate name.

To configure your network device for gRPC services with server-only authentication:

  1. Navigate to the SSL-based API connection settings for gRPC services.
  2. Configure the port to use for gRPC services.

    For example:

  3. Specify a local certificate name.

    Enter the identifier for the local certificate that you previously loaded into the Junos PKI with the request security pki local-certificate load operational mode command.

    The following example configures the local certificate gnoi-server:

  4. Configure the device to use the PKI database for certificates.
  5. Enable the device to reload certificates without terminating the gRPC session.
  6. (Optional) Specify an IP address to listen to for incoming connections.

    For example:

    Note:

    If you do not specify an IP address, the default address of :: is used to listen for incoming connections.

  7. (Optional) Configure tracing for extension services to debug any issues that might arise.
    Note:

    To view Junos OS Evolved trace files for extensions services, use the show trace application jsd and show trace application jsd live operational mode commands.

  8. Commit the configuration.

To configure mutual authentication instead of server-only authentication, you must also complete the steps in Configure Mutual (Bidirectional) Authentication for gRPC Services.

Configure Mutual (Bidirectional) Authentication for gRPC Services

You can configure mutual (bidirectional) authentication for gRPC sessions, which authenticates both the network device as the gRPC server and the network management system as the gRPC client using SSL certificates. The Junos device uses the credentials provided by the external client to authenticate the client and authorize a connection.

You can configure mutual authentication for gRPC sessions at the [edit system services extension-service request-response grpc ssl] hierarchy level as outlined in this section. Alternatively, for gNOI operations, you can initially set up server-only authentication and then load the client CA certificates using the gNOI certificate management (cert) service RPCs. The gNOI server only supports one global CA certificate bundle for gNOI services. When you use gNOI to load the CA certificate bundle, the device implicitly uses mutual authentication, and you do not need to perform the steps outlined in this section. However, you should take note of the following:

  • gNOI always loads the CA certificate bundle using the ca-profile-group reserved identifier gnoi-ca-bundle.

  • If you use gNOI to load the CA certificate bundle, the device implicitly uses mutual authentication and assumes the following configuration, even though it is not explicitly configured on the device.

  • If the gNOI server receives a request to load a new CA certificate bundle, it clears the certificates for the previous CA bundle from the device and loads the new ones.

  • If you use gNOI to load a CA certificate bundle and you also configure the [edit system services extension-service request-response grpc ssl mutual-authentication] statement hierarchy, then the configured statements take precedence.

Before you begin:

To configure authentication for the external client, that is, the network management system (when you do not intend to use gNOI to load the CA certificates at a later time):

  1. Download the Root CA certificate that will be used to validate the client' s certificate to the local device.
  2. Configure the certificate authority profile for the client certificate's Root CA at the [edit security pki] hierarchy.

    For example:

  3. Commit the configuration.
  4. In operational mode, load the Root CA certificate that will be used to verify the client's certificate into the Junos PKI. Specify the ca-profile identifier that you configured in the previous steps.

    For example:

    Tip:

    To load a CA certificate bundle, issue the request security pki ca-certificate ca-profile-group load ca-group-name ca-group-name filename bundle-path command.

    After loading the certificate, enter configuration mode and continue configuring mutual authentication.

  5. Enable mutual authentication and specify the requirements for client certificates.

    For example, to specify the strongest authentication, which requires a certificate and its validation, use require-certificate-and-verify.

    Note:

    The default is no-certificate. The other options are: request-certificate, request-certificate-and-verify, require-certificate, require-certificate-and-verify.

    We recommend that you use the no-certificate option in a test environment only.

  6. Specify the certificate authority profile that will be used to verify the client certificate.

    The certificate authority profile was configured in step 2.

    For example, to specify a certificate authority profile named gnoi-client:

  7. Commit the configuration.

Configure the User Account for gRPC Services

Channel credentials are attached to the gRPC channel and enable the client application to access the service. Call credentials are attached to a specific RPC request and provide information about the user who is using the client application. You must provide call credentials in each RPC request, which requires a user account for the network device. The user must have a user account defined locally on the network device, or the user must be authenticated by a TACACS+ server, which then maps the user to a user template account that is defined locally on the device.

To create a user account:

  1. Configure the user statement with a unique username, and include the class statement to specify a login class that has the permissions required for all actions to be performed by the user. For example:
  2. For local user accounts, configure the user's password.

    You can omit the password for local user template accounts because the user is authenticated through a remote authentication server.

  3. (Optional) Configure the full-name statement to specify the user’s name.
  4. Commit the configuration to activate the user account on the device.
  5. Repeat the preceding steps on each network device where the gRPC client will execute RPCs in a gRPC session.
After enabling gRPC services on the network device, set up the remote network management system as a gRPC client. To enable the client to execute gNOI operations, configure the client as outlined in Configure gNOI Services.