Help us improve your experience.

Let us know what you think.

Do you have time for a two-minute survey?

 
ON THIS PAGE
 

Configure gRPC Services

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

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 and Authorization for gRPC-based Services

The gNOI, gNMI, and gRIBI interfaces 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 gRPC client and server.

Figure 1: gRPC Server and Client Interaction gRPC 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 gRPC-based 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.

By default, Junos devices authorize an authenticated gRPC client to execute all gRPC RPCs. You can optionally configure a gRPC user's login class to explicitly allow or deny specific gRPC RPCs. To specify the RPCs, you configure the allow-grpc-rpc-regexps and deny-grpc-rpc-regexps statements and define regular expressions that match the RPCs. See Configure gRPC RPC Authorization for more information.

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, gRPC clients can then use any micro-service to update the certificate. For example, a gRPC client can use the gNOI CertificateManagement service to install a new certificate or replace an 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 that identifies the gRPC server.

After you enable gRPC services and specify a local certificate, the network device uses server-only authentication. You can then optionally configure mutual authentication by completing the steps described in Configure Mutual (Bidirectional) Authentication for gRPC Services.

To configure your network device for gRPC services and specify the local certificate used for server 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.

    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 on Junos devices using one of the following options:

  • Configure the mutual authentication settings directly under the [edit system services extension-service request-response grpc ssl mutual-authentication] hierarchy level.

  • Set up server-only authentication initially, and then use the gNOI CertificateManagement service to load the necessary CA certificates on the device.

If you configure mutual authentication directly in the device configuration, the device configuration takes precedence over any setup done using the gNOI services.

Before you begin:

The following sections discuss the different methods for configuring mutual authentication. You can use whichever method works best for your environment.

Configure Mutual Authentication in the Device Configuration

To configure authentication for the gRPC client directly in the network device configuration:

  1. Download the root CA certificate that will be used to validate the client' s certificate to the local device acting as the gRPC server.

  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 the certificate authority profile named gnoi-client:

  7. Commit the configuration.

Configure Mutual Authentication Using the gNOI CertificateManagement Service

You can use the gNOI CertificateManagagment service to set up mutual authentication between the gRPC client and gRPC server instead of configuring the settings directly in the device configuration. You initially set up server-only authentication and then use the gNOI CertificateManagement service RPCs to load the client CA certificates. See gNOI Certificate Management Service for information about loading the certificates using the gNOI CertificateManagagment service.

The gRPC server supports only one global CA certificate bundle for gNOI services. When you use the gNOI CertificateManagagment service to load the CA certificate bundle, the device implicitly uses mutual authentication. However, you should take note of the following:

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

  • If you use the CertificateManagagment service 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 CertificateManagagment service sends a request to load a new CA certificate bundle, the server clears the certificates for the previous CA bundle from the device and loads the new ones.

  • If you use the CertificateManagagment service 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.

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.

Configure gRPC RPC Authorization

By default, Junos devices authorize an authenticated gRPC client to execute all gRPC RPCs. You can configure a Junos login class to explicitly allow or deny gRPC RPCs. To specify the RPCs, you configure the allow-grpc-rpc-regexps and deny-grpc-rpc-regexps statements and define regular expressions that match the RPCs. If there are conflicting expressions in the allow and deny lists, the deny list takes precedence. If an RPC does not match either list, the RPC is allowed by default.

Junos devices use the following syntax for specifying gRPC RPCs:

where package, service, and rpc are the names defined in the respective statement in that service's proto definition file. For example:

You can configure multiple allow-grpc-rpc-regexps and deny-grpc-rpc-regexps statements with one or more expressions. Enclose each expression within quotation marks (" "). Enclose multiple expressions in square brackets [ ], and separate the expressions with a space.

To create a login class that defines authorization for gRPC RPCs:

  1. Configure the login class name and permissions.

    For example:

  2. Within the class, configure regular expressions for the RPCs that the class allows.

    For example, the following statement allows the gNMI Get() RPC and all gNOI System service RPCs.

  3. Configure regular expressions for the RPCs that the class denies.

    For example, the following statements deny the gNMI Set() RPC and also deny all RPCs for the gRIBI service as well as the gNOI CertificateManagement service.

  4. Assign the login class to the appropriate gRPC users.

    For example, the following statement assigns the grpc-operator class to the grpc-user user.

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.